기술 문서는 코드가 컴파일된 후에 끝내는 부수적인 작업이 아닙니다. 기술 문서는 모든 소프트웨어 프로젝트의 중심에 자리 잡고 있으며, 새로운 개발자가 첫날에 버그를 수정할 수 있을지, 아니면 사용자가 5분 만에 혼란을 느끼고 제품을 포기할지를 결정합니다. 좋은 문서는 사용자가 실제 작업을 완수하도록 돕습니다. 또한 미래의 유지보수자가 모듈이 왜 존재하는지, 그리고 모든 것을 망가뜨리지 않고 어떻게 변경할 수 있는지를 이해하도록 돕습니다. 하지만 너무 많은 팀이 문서를 나중에 생각하는 부차적인 일, 즉 급하게 작성한 README나 방치된 위키 페이지 정도로 취급합니다. 진정으로 유용한 문서를 작성하는 것은 의도적으로 개선할 수 있는 기술입니다.
작성하기 전에 독자를 파악하세요
제목을 하나라도 쓰기 전에 누가 읽을 것인지 결정하십시오. 커넥션 풀 설정을 찾는 데이터베이스 관리자는 React 컴포넌트 props를 찾는 프론트엔드 개발자와는 공통점이 전혀 없습니다. 최종 사용자는 아키텍처 다이어그램이 아니라 번호가 매겨진 단계와 스크린샷이 필요합니다. 그들은 렌더링 파이프라인이 어떻게 작동하는지가 아니라 PDF를 어떻게 내보내는지 알고 싶어 합니다. 라이브러리를 통합하는 개발자에게는 정확한 함수 시그니처, 에러 코드, 그리고 복사해서 붙여넣을 수 있는 코드 스니펫이 필요합니다. 시스템 관리자에게는 설치 전제 조건, 환경 변수, 그리고 가장 흔한 실패 모드부터 시작하는 문제 해결 흐름이 필요합니다.
만약 이 세 그룹 모두를 하나의 방대한 텍스트로 만족시키려 한다면, 모두가 손해를 보게 됩니다. 별도의 경로를 만드세요. 단일 페이지라도 "운영자를 위한 안내"나 "클라이언트 개발자를 위한 안내"와 같이 명확한 제목을 사용하여 깔끔하게 구분할 수 있습니다. 목표는 "이 단락이 나를 위한 것인가?"라고 자문하며 느끼는 정신적 마찰을 제거하는 것입니다.
불필요한 요소를 제거하세요
명확함이 기교보다 낫습니다. 짧은 문장을 사용하세요. 능동태를 사용하세요. "데이터베이스를 초기화하십시오"가 "데이터베이스는 사용자에 의해 초기화되어야 합니다"보다 더 명확합니다. 'idempotency(멱등성)'나 'serialization(직렬화)'과 같은 기술 용어를 반드시 사용해야 한다면, 본문 내에서 정의하거나 용어 사전으로 링크를 연결하십시오. 사전 지식이 있다고 가정하지 마십시오.
한 가지 실질적인 테스트 방법은 작성한 단락을 소리 내어 읽어보는 것입니다. 숨이 차다면 문장이 너무 긴 것입니다. 또 다른 테스트는 화려한 동사를 단순한 동사로 바꾸는 것입니다. "utilize the API"라는 문구가 의미를 잃지 않고 "use the API"로 바뀔 수 있다면, 그렇게 수정하십시오. 쉬운 언어가 수준을 낮춘 언어를 의미하는 것은 아닙니다. 그것은 기업 특유의 미사여구를 걷어낸 정밀한 언어를 의미합니다.
실제로 도움이 되는 구조
정리되지 않은 매뉴얼은 매뉴얼이 아예 없는 것보다 더 많은 시간을 낭비하게 만듭니다. 문서를 깔때기라고 생각하십시오. 상단에는 프로젝트가 무엇을 하는지, 누가 관심을 가져야 하는지를 설명하는 짧은 개요를 배치하십시오. 그다음에는 독자의 로컬 환경에 대해 아무것도 가정하지 않는 설치 지침을 따르게 합니다. 그런 다음 처음부터 끝까지 완전하고 현실적인 시나리오를 안내하는 튜토리얼을 추가하십시오. 그다음은 API 레퍼런스입니다. 이는 포괄적이면서도 훑어보기 쉬워야 하며, 알파벳 순서로 나열하기보다는 리소스나 기능별로 그룹화해야 합니다. 마지막으로 특정 증상을 다루는 문제 해결 가이드를 배치하십시오. "Connection refused" 메시지를 받는 사용자는 "Permission denied"를 보는 사용자와는 다른 답변이 필요합니다. 에러를 추상적인 카테고리가 아닌 메시지나 문맥에 따라 그룹화하십시오.
목록과 코드 블록은 빽빽한 텍스트를 나누어 독자가 필요한 정확한 명령어를 빠르게 찾을 수 있게 해줍니다. 적절한 위치에 배치된 글머리 기호 목록은 혼란스러운 단락을 일련의 실행 단계로 바꿀 수 있습니다.
설명만 하지 말고 보여주세요
추상적인 설명은 사용자를 좌절하게 만듭니다. 도구의 구성 방법을 설명한다면, 정확한 파일 내용을 보여주십시오. 설치, 초기화 및 일반적인 구성을 위한 코드 스니펫을 제공하십시오. 샘플 입력값과 예상 출력값을 나란히 보여주십시오. API가 JSON을 반환한다면 JSON을 보여주십시오. CLI 도구가 표 형식의 출력을 생성한다면 표를 보여주십시오. 워크플로에 대한 설명이 시연과 동일할 것이라고 절대 믿지 마십시오.
가장 중요한 것은 게시하기 전에 깨끗한 환경에서 모든 예제를 테스트하는 것입니다. 자신의 코드 스니펫을 새로운 컨테이너나 가상 머신에 복사해 보십시오. 의존성에 대해 언급하는 것을 잊어 실패한다면, 당신은 수많은 문제로부터 스스로를 구한 것입니다. 구체적인 예시는 불확실성을 행동으로 바꿔주기 때문에 기술 문서 작성에서 가장 큰 투자 대비 효과(ROI)를 제공합니다.
생명력을 유지하세요
문서는 코드보다 더 빨리 노후화됩니다. 메서드 시그니처가 바뀌고, 기본 포트가 변경되고, 의존성이 교체되면 갑자기 당신의 지침이 막다른 길로 이어지게 됩니다