기술 문서를 작성할 때 가장 중요하게 생각하는 요소는 무엇인가요?

개발 문서를 작성할 때 가장 중요하게 생각하는 것은 독자가 누구인지입니다. 같은 API 문서라도 처음 보는 외부 개발자와 내부 팀원을 대상으로 할 때 필요한 맥락의 양이 다릅니다. 팀 프로젝트에서 온보딩 문서를 작성했을 때 처음에는 기술 용어를 그대로 썼는데, 새 팀원이 읽고 나서 모르는 부분이 많다고 해서 전제 지식 수준을 낮춰 재작성한 경험이 있습니다.

예시 코드를 함께 넣는 것이 설명문만 있을 때보다 훨씬 이해가 빠르다는 것도 이 과정에서 배웠습니다. 또한 문서는 최신 상태를 유지하는 것이 중요한데, 코드가 바뀌면 문서도 함께 업데이트하는 습관을 PR 체크리스트에 넣어 팀 전체가 지키도록 했습니다. 한계는 문서 업데이트를 강제하기 어렵다는 점인데, 자동화 도구를 이용해 코드와 문서가 분리되는 경우를 줄이는 방향을 고민하고 있습니다. 좋은 문서는 읽는 사람의 다음 행동을 명확히 만드는 것이라는 결을 갖고 있습니다.