이 질문 뒤에 면접관이 확인하려는 것은 따로 있습니다.
개발 문서를 작성할 때 가장 중요하게 생각하는 것은 독자가 누구인지입니다. 같은 API 문서라도 처음 보는 외부 개발자와 내부 팀원을 대상으로 할 때 필요한 맥락의 양이 다릅니다. 팀 프로젝트에서 온보딩 문서를 작성했을 때 처음에는 기술 용어를 그대로 썼는데, 새 팀원이 읽고 나서 모르는 부분이 많다고 해서 전제 지식 수준을 낮춰 재작성한 경험이 있습니다.
예시 코드를 함께 넣는 것이 설명문만 있을 때보다 훨씬 이해가 빠르다는 것도 이 과정에서 배웠습니다. 또한 문서는 최신 상태를 유지하는 것이 중요한데, 코드가 바뀌면 문서도 함께 업데이트하는 습관을 PR 체크리스트에 넣어 팀 전체가 지키도록 했습니다. 한계는 문서 업데이트를 강제하기 어렵다는 점인데, 자동화 도구를 이용해 코드와 문서가 분리되는 경우를 줄이는 방향을 고민하고 있습니다. 좋은 문서는 읽는 사람의 다음 행동을 명확히 만드는 것이라는 결을 갖고 있습니다.
API 문서를 처음 작성할 때 내부 팀원을 대상으로 쓴다고 생각하고 기술 용어를 충분한 설명 없이 썼습니다. 그런데 신규 입사자가 읽고 나서 '왜 이 API를 쓰는지, 어떤 순서로 호출해야 하는지가 없다'고 했습니다. 문서가 구현 내용은 설명했지만 왜 이렇게 설계됐는지, 어떻게 써야 하는지는 빠져 있었던 것입니다. 재작성할 때는 사전 지식 없는 독자 기준으로 세 가지를 추가했습니다. ① 이 API가 어떤 문제를 해결하는지 한 줄 요약 ② 호출 순서와 의존 관계 ③ 흔히 틀리는 케이스. 재작성 후 다음 입사자의 온보딩 시간이 눈에 띄게 줄었습니다.
좋은 문서는 코드가 무엇인지가 아니라 독자가 다음에 무엇을 해야 하는지를 안내한다는 결을 이 경험에서 얻었습니다.
개발 문서에서 가장 지키기 어려운 것이 최신 상태 유지라고 생각합니다. 코드가 바뀐 뒤 문서가 그대로 남으면, 그 문서를 보고 구현한 사람이 오류를 냅니다. PR 체크리스트에 '문서도 함께 수정했나요'를 넣었더니 많이 줄기는 했지만 완전히 막지는 못했습니다. 이후 API 스펙은 코드에서 자동 생성하는 방식(Swagger 연동)으로 전환해서 코드와 문서가 분리될 수 없는 구조를 만들었습니다. 다만 자동 생성된 문서는 정확하지만 맥락 설명이 빠진다는 한계가 있어서, 자동 생성 부분과 수동 서술 부분을 분리하는 방식으로 보완했습니다.
자동화할 수 있는 부분과 사람이 써야 하는 부분을 나누는 것이 문서 관리의 현실적인 전략이라는 결을 얻었습니다. 완벽한 문서보다 덜 틀리는 구조가 더 중요합니다.
답변에서 흔히 빠지는 것들 — 빠져 있으면 꼬리질문이 깊어집니다.
이 질문에 이어 HL그룹 품질관리 면접관이 던질 가능성이 높은 후속 질문.
이 페이지의 질문·답변·꼬리질문은 유사 직군 채용 시장의 공개된 면접 후기·커뮤니티 게시물을 분석해 구성한 학습 자료입니다. 특정 회사가 실제로 이 질문을 출제했다는 것을 보장하지 않으며, 모든 예시는 우문현답이 직접 작성한 창작물입니다. 해당 회사의 공식 입장과는 무관합니다. 회사 측의 정정 요청이 있을 경우 24시간 이내에 응답·수정합니다.