한빛출판네트워크

웹 개발자가 만날 수 있는 두 가지 시나리오를 잠시 상상해보죠.

첫 번째 시나리오에서는 할로우(Harlow)를 만나봅니다. 오늘 할로우는 새로운 프로젝트에 참여합니다. 새로 만나게 될 팀은 잘 정립된 코드베이스, 훌륭한 작업 환경, 견고한 테스트 스위트를 갖추고 있습니다. 이런 좋은 환경 덕분에 할로우는 새로운 사무실에 들어서면서 팀의 업무 속도쯤은 손쉽게 따라갈 수 있을 것 같은 기분이었습니다. 아침 스탠드업 미팅이 끝나고 동료인 라일리(Riley)가 조심스럽게 프로젝트에 필요한 설치 문서에 관해 이야기해주었습니다. 그는 문서가 "최신의 정보는 아니지만, 아마도 일을 진행하는 데 큰 무리는 없을 것"이라고 말했습니다. 할로우는 문서를 따라 필요한 도구를 설치하려는 시도에 반나절 넘게 허비해버립니다. 그러다가 결국에는 직접 코드를 까보거나 동료에게 도움을 요청해야 했습니다. 아침에 기분 좋았던 느낌이 지루한 혼란 속의 하루로 바뀌기에는 많은 시간이 필요하지 않았습니다.

두 번째 시나리오에서는 해리슨(Harrison)을 만나봅니다. 해리슨은 웹앱을 개발합니다. 몇 가지를 살펴보고 자신의 프로젝트에 매우 유용하다고 생각되는 라이브러리를 찾았습니다. 하지만, 자신의 코드베이스와 통합을 시도하면서 라이브러리 API의 일부는 문서가 대충 작성되었거나 심지어 문서로 만들어지지 않은 것을 발견합니다. 결국 그는 다른 솔루션을 찾아야 했습니다.

이런 시나리오는 약간 과장될 수도 있지만, 많은 이들이 비슷한 경험을 가지고 있음을 분명 확신합니다. 이런 문제는 주로 낮은 품질의 코드 때문이 아니라 잘못된 문서화로 발생합니다.

유용한 문서가 성공적인 프로젝트와 개발자 삶의 질에 너무 중요하다면, 왜 모든 프로젝트가 그렇게 하지 못할까요? 대답은 좋은 코드와 마찬가지로 훌륭한 문서는 작성하기가 어렵고 많은 시간이 필요하기 때문입니다..

훌륭한 문서를 만들기 위해서 따라야 할 8가지 원칙이 있습니다.

1. 명확하고 친절한 문서를 작성해야 합니다.
2. 프로젝트의 모든 측면을 자세히 설명하는 포괄적인 문서를 작성해야 합니다.
3. 빠르게 살펴볼 수 있는 문서를 작성해야 합니다.
4. 소프트웨어 사용법에 대한 예제를 제공하는 문서를 작성해야 합니다.
5. 필요한 경우 같은 내용을 반복적으로 포함하는 문서를 작성해야 합니다.
6. 최신 상태로 유지할 수 있는 문서를 작성해야 합니다.
7. 누구나 기여하기 쉬운 문서를 작성해야 합니다.
8. 쉽게 찾을 수 있는 문서를 작성해야 합니다.

좋은 문서화의 가장 중요한 원칙은 될 수 있는 한 친절하게 만드는 것입니다. 이 말은 어떤 단계를 건너뛰지 않고 가능한 가장 명확한 용어로 문서를 작성해야 한다는 것을 의미합니다. 문서를 작성하면서 사용자가 어떤 것을 이미 알고 있을 거라고 가정하지 말아야 합니다. 때로는 너무 지나쳐 보이기도 합니다. "모든 X 개발자는 Y에 대해 알고 있어"라고 말하고 싶은 유혹을 받을 수도 있습니다. 그러나 이 과정에서 우리는 자신의 지식과 경험을 반영하는 실수를 합니다. 이렇게 만들어지는 문서는 장황한 내용을 담고 있지만, 모든 개발자의 경험을 담고 있지 못하기 때문에 충분한 정보를 전달할 수 없습니다.

문서화는 포괄적인 것을 목표로 해야 합니다. 즉, 프로젝트의 모든 측면이 문서화 대상입니다. 문서화되지 않은 기능이나 예외는 사용자에게 혼란으로 이어질 수 있으며 나중에 참여한 개발자는 필요한 답변을 찾기 위해 문서 대신 코드를 뒤지는데 많은 시간을 허비하게 됩니다. 모든 기능을 완벽하게 문서에 담으면 이러한 모호성은 사라집니다.

문서를 빠르게 살펴볼 수 있게 하는 것도 중요합니다. 이렇게 만들어진 문서에서 사용자는 원하는 내용을 쉽게 찾을 수 있습니다. 명확한 제목, 기호 목록이나 링크를 사용하면 문서를 쉽게 읽도록 만들 수 있습니다. 대형 프로젝트를 다루는 문서는 목차나 명확한 탐색 기능을 사용해 하나의 긴 문서를 스크롤 하지 않고 사용자가 필요한 항목으로 바로 건너뛰도록 합니다.

예제가 있는 문서를 바탕으로 사용자는 코드를 어떻게 사용할 수 있는지 확인할 수 있습니다. 프로젝트에서 가장 일반적으로 사용하는 예제를 제공하면서 모든 상황을 자세히 설명하는 포괄적인 문서를 만들어야 합니다.

문서 내에 반복이 포함될 수 있다는 것을 받아들여야 합니다. Write the Docs project 그룹에서는 ARID(Accepts some Repetition In Documentation)라고 표현합니다. 사용자는 모든 문서를 다 읽는 것이 아니며, 일부 정보는 여러 문서에 분산될 수 있습니다. 좋은 코드의 원칙은 중복 배제(DRY, Don't repeat yourself)입니다. 하지만, 좋은 글쓰기의 목표는 명확함이며, 이를 위해 같은 내용을 반복해서 문서에 담을 수 있습니다. Write the Docs project 그룹에서는 ARID, DRY, WET(Write Everything Twice)을 이렇게 설명하고 있습니다.

반복을 최소화하는 노력은 당연히 중요합니다! 단어 자체로도 그렇듯이 ARID(땅이나 기후가 매우 건조한)는 WET(비가 오는, 궂은)을 의미하지 않습니다. 가능한 건조(DRY)하게 유지하는 것은 우선적인 원칙입니다. 하지만, 문서를 작성하기 위해서는 상황에 따라 약간의 "수분(moisture)"이 필요할 수 있다는 것을 알아야 합니다.

효과적인 문서는 최신 상태로 유지해야 합니다. 간단한 이야기 같지만, 생각보다 쉽지 않은 도전입니다. 프로젝트가 시작할 때는 훌륭한 문서를 만들겠다고 의욕적으로 시작할 수 있지만, 소프트웨어 개발이 속도를 내고, 빠른 반복을 지속하는 과정에서 문서는 보조를 맞추지 못할 수 있습니다. 애자일 개발 팀의 일원으로 일하는 경우 팀에서 정한 "완료의 정의(definition of done; DOD)"를 문서에 추가하는 것이 좋습니다. 독립적인 프로젝트의 경우라면 문서를 중요한 마지막 단계로 다루십시오.

기여하기 쉬운 문서는 최신 상태를 유지하기 쉽습니다. 문서를 쉽게 작성하게 하는 가장 간단한 방법은 코드와 마찬가지로 소스 관리 시스템에서 텍스트 자체를 관리하는 것입니다. Docs Like Code 사이트에서는 소스 관리 시스템을 사용하고 빌드를 자동화하는 소프트웨어 개발 도구와 기법을 문서화에 적용함으로써 코드처럼 문서를 다루는 것을 권장하고 있습니다.

문서는 쉽게 찾을 수 있어야 유용합니다. 리드미(README) 파일을 최신의 상태로 유지하고 리드미 파일 앞부분에 사용자에게 필요한 문서의 목록을 링크로 제공해주기만 해도 검색 가능성을 간단하게 높일 수 있습니다.

이 지침이 프로젝트 문서 초안을 작성할 때 유용하게 사용되기를 바랍니다. 때로는 문서가 다른 개발자를 위한 것이 아니라 종종 우리의 미래를 위한 것임을 기억하세요. 몇 개월이 지난 후에 프로젝트를 돌아보면 명확하고 최신 상태로 유지된 문서가 얼마나 고마운지 새삼 느끼게 될 겁니다.

*****

원문 : The eight rules of good documentation

번역 : 이준하