이 문서는 카카오디벨로퍼스의 기술 문서 작성 방법을 단계별로 안내합니다. 이 문서의 내용은 일반적인 테크니컬 라이팅(Technical Writing) 원칙에 기반하므로 기술 문서 종류와 무관하게 적용할 수 있으며, 다른 서비스의 기술 문서 작성 시에도 참고할 수 있습니다.

기술 문서는 일정하고 체계적인 작성 과정과 규칙에 따라 작성할 수 있습니다. 아래는 일반적인 기술 문서 작성 과정을 단계적으로 정리한 표입니다.

작성하려는 기술 문서에 대해 아래 네 가지 항목을 정의해야 합니다.

목적과 독자 유형에 맞춰 문서 종류, 배치를 정해야 합니다.

먼저, 무엇을 위한 기술 문서를 작성하는지 목적과 독자 유형을 명확히 정의합니다. 기술 문서는 목적별로 탐색에 효율적인 구성으로 형식화할 수 있고, 독자 유형에 따라 제공할 정보의 범위나 표현 방식을 달리해야 하기 때문입니다.

이어서 작성하려는 기술 문서의 목적과 독자 유형에 따라 문서 종류를 선택합니다. 문서 종류를 정의해두면 보다 확실한 목적을 가지고 글을 쓸 수 있고, 문서 종류별로 기본적인 목차나 형식이 정해져있어 작성해야 할 내용도 명확해집니다. 카카오디벨로퍼스의 제품별 문서 구성을 기준으로 예를 들면 아래와 같습니다.

• 목적별 문서 종류 선택
  • 제품 사용 시 필요한 설정에 대해 안내하는 기술 문서는 설정하기
  • API 사용 방법을 안내하기 위한 기술 문서는 개발 문서
• 독자 유형별 문서 종류 선택
  • 모든 사용자를 위한 주요 개념 설명 문서는 이해하기
  • 개발자를 위한 API 사용 방법 안내는 개발 문서

문서 종류를 정했다면 기술 문서를 문서 내 어떤 경로에, 어떤 정보와 같이 배치할지 결정합니다. 카카오디벨로퍼스의 제품별 문서 구성을 기준으로 예를 들면 아래와 같습니다.

• 목적별 문서 배치
  • 제품별 추가 기능을 소개하기 위한 기술 문서는 해당 제품 카테고리 하위에 배치
  • 새로운 제품은 별도 제품 카테고리를 생성해 배치
• 독자 유형별 문서 배치
  • 카카오 및 공동체만 사용할 수 있는 기능의 기술 문서는 인하우스/공동체 문서에 배치

Kakao SDK for iOS를 사용한 카카오 로그인 구현 방법 안내 문서는 목적, 독자 유형, 문서 종류, 배치를 아래와 같이 정의할 수 있습니다.

기술 문서 안에 포함할 정보를 체계적으로 수집하고 분류해 문서의 큰 틀인 구조를 정합니다.

독자에게 전달해야 할 구체적인 정보를 조사 및 취합합니다. 문서 종류별로 필요한 정보를 수집합니다. 카카오디벨로퍼스의 제품별 문서 구성을 기준으로 예를 들면 아래와 같습니다.

• 이해하기: 제품 기능 및 규격, 주요 개념과 용어, 활용 사례, 참고 정보 등
• API 개발 문서: 요청 및 응답 규격, 이용 정책, 예제 등
• 공지사항: 일정, 변경 사항, 영향 범위 등 알릴 사실에 대한 구체적인 정보

모은 정보는 체계적으로 분류합니다. 분류 과정을 거쳐 단순 나열된 사실들을 독자에게 가치 있는 정보로 가공하고, 문서 구조를 도출할 수 있습니다. 카카오디벨로퍼스의 문서로 예를 들면 아래와 같습니다.

1. 계획 시 수집한 정보를 종류별로 분류
   • 이해하기: 제품의 각 기능 정보와 활용 사례를 기능 소개로 분류
   • REST API: 메서드(Method), 엔드포인트(Endpoint), 파라미터(Parameter) 정보를 요청 규격으로 분류
2. 각 정보에 중요도와 우선순위 부여
   • 중요도와 우선순위는 독자 관점에서 판단해야 하며, 불필요한 정보는 제외
   • 다른 정보를 포괄하는 상위 개념일수록 높은 중요도와 우선순위 부여
   • 주요 개념이나 기능 정의와 같이 먼저 전달되어야 하는 정보에 높은 우선순위 부여
3. 중요도 높고 기준이 될 수 있는 정보들로 문서 목차 구성
   • 연관된 정보들을 문서 목차와 같은 트리(Tree) 형태로 정리
   • 각 목차 항목은 대제목, 중제목, 소제목의 최대 3단계로 구성

여러 기술 문서들의 목차를 살펴보면 모두 정보 단위로 목차가 구성되어 있고, 필요에 따라 순서나 참고 정보를 덧붙이고 있다는 사실을 알 수 있습니다. 예를 들어, Google Play 고객센터의 도움말 주제 목차는 아래와 같이 관련 정보들을 체계적으로 분류해 제공합니다.

• Google Play 시작하기
  • Google Play 스토어에서 Android 앱 및 디지털 콘텐츠 다운로드하기
  • Google Play 보호자 가이드
  • Google Play 스토어 앱 찾기
  • ...
• 자주 사용되는 도움말
  • Google Play 환불 자세히 알아보기
  • 알 수 없는 청구 내역 신고하기
  • 계정의 결제 문제해결
  • ...
• Google Play 사용
  • Android 앱 및 게임 사용
  • 기기 또는 컴퓨터에서 Google Play 사용
  • Google Play Pass 시작하기
  • ...

아래 항목 점검 후 문서 내용을 작성해야 합니다.

• 서식이 있는가?
  • 서식이 있는 경우, 서식을 바탕으로 초안 작성
  • 서식이 없는 경우, 정리된 목차대로 문서 구조 작성
• 같은 개념이나 대상을 일관된 용어로 지칭하는가?
  • 같은 개념이나 대상을 서로 다른 표현으로 지칭하지 말 것
  • 일관된 용어를 정해 문서에 사용
• 독자 눈높이에 맞는 정보를 제공하는가?
  • 목적과 독자 유형을 고려했을 때 불필요한 정보는 제외
  • 어려운 내용은 풀어쓰거나 참고 정보 제공

문서 계획 및 구조 설계를 바탕으로 정보를 채워넣어 문서 내용을 작성해야 합니다. 기술 문서는 소설처럼 시간의 흐름에 따라 사건이 전개되는 구조가 아니라, 단편적인 정보들을 나열하는 구조입니다. 목차별 내용을 아래와 같이 단계적으로 채웁니다.

1. 각 목차 항목에 포함할 정보 나열
2. 정보마다 상세 내용과 설명 추가
3. 논리의 흐름에 따라 정보 나열 순서 조정

숙련된 테크니컬 라이터(Technical writer)라도 초안을 완벽하게 쓰는 건 어렵습니다. 이후 검토 과정에서 초안의 부족한 점을 개선할 수 있습니다.

아래 카카오디벨로퍼스의 종류별 기술 문서를 참고합니다.

• 카카오 로그인 > 이해하기(제품 소개서)
• 카카오 로그인 > 설정하기(설정 안내서)
• 카카오 로그인 > REST API(개발 문서)
• 카카오 로그인 > 에러 코드
• 카카오싱크 > FAQ

기술 문서가 올바르게 작성되었는지 목차와 내용을 점검해야 합니다.

검토 단계에서는 초안을 검토해 오류를 수정하거나 부족한 점을 보완합니다. 검토는 기술 문서의 내용을 검증하고 개선하는 단계로, 기술 문서 작성 과정에서 가장 중요합니다.

문서 작성자가 최소 1회 이상 검토를 수행해야 합니다. 보다 완성도 높고 꼼꼼한 기술 문서로 완성될 수 있도록 동료들과 함께 검토하기를 권장합니다. 주요 검토 항목은 아래와 같습니다.

• 사실 확인
  • 최신 정보와 대조해 잘못되었거나 변경해야 할 내용이 없는지 확인
  • 의미가 명확하지 않은 표현 개선
• 사용성 검증
  • 문서의 안내나 예제를 직접 실행해 보고 문제 없는지 점검
  • 요구사양, 개발 환경, 정책 등 참고 정보 보완
• 문서 편집
  • 철자, 맞춤법 오류가 없는지 확인 (참고: Daum 맞춤법 검사기)
  • 이해하기 어렵거나 가독성이 나쁜 문장이나 표현 개선

아래는 기본적인 체크리스트 예시입니다.

완성된 기술 문서를 사용자가 볼 수 있도록 배포해야 합니다. 주요 배포 방식은 아래와 같습니다.

* Swagger, Notion, Gitbook, Confluence 등

• 문서 내용 작성 가이드

• 카카오디벨로퍼스 문서 정보