기술 문서 작성을 위한 문서 유형

🐾들어가며

Docs for Developers 의 chapter 2 문서화 계획하기를 읽고 예시를 찾아보면서 같이 정리했습니다.

이번 챕터에서는 각 문서의 종류와 문서를 작성하기 위한 포괄적인 계획을 세워보는 것을 목표로 합니다.

✨본격적으로

✅문서의 유형

코드 주석, 리드미, 시작하기, 개념, 절차, 참조 문서

문서의 종류는 위와 같이 6가지로 소개하고 있습니다. 그 중 개발 문서라고 하면 흔히 생각나는 API와 RELEASE NOTE 등은 REFERENCE 유형입니다.

✅각 문서의 특징과 예시

이제 유형을 하나씩 보면서 어떤 특징이 있는지 등에 대해 정리해보겠습니다. 또한, 그동안 공식 문서들을 읽을 때 대부분 비슷한 형태로 쓰여져 있는지 알 듯 합니다. 그래서 예시를 좀 찾아보면서 비교해보려고 합니다.

1. 코드 주석

내용

• 설계 결정 사항
• 코드 작성 시 택한 트레이드오프
• 무슨 일을 했고 왜 그렇게 했는지

특징

• 간결하다.
• 코드와 관련한 설명을 담는다.
• 자유롭게 사용하되 지나치게 사용하지 않는다.

 

2. README

역할 : 이 코드가 어떤 문제를 해결하고 왜 중요한지 이해할 수 있도록 도와준다.
내용 : 저장소에 포함된 코드를 요약하는 내용

• 코드가 상위 수준에서 하는 일
• 설치 방법
• 문제 해결 단계
• 코드 유지 관리자
• 라이선스 정보
• 변경 로그
• 기본 사용 예시
• 심화 자료와 문서 링크

특징

• 간결하며 유익하고 정확한 최신 정보를 보여준다.

예시 : https://github.com/pmndrs/zustand

리드미 템플릿

코드가 상위 수준에서 하는 일을 요약하는 한두 개의 단락  
## 설치 
1. 2. 3. 4. 5.  

## 사용 예시  

## 문제 해결  

## 변경 로그  

## 추가 자료  

## 라이선스 정보    

## ✔️결론

 

3. STARTUP 시작하기 문서

역할 : 제품의 첫인상과 함께 사용자를 첫 번째 사용자 경험으로 안내

작성 전 질문

• 이 서비스가 무엇이고 서비스의 핵심 기능이 무엇인지 가장 빨리 설명할 수 있는 방법은?
• 이 제품을 설치하고 사용하는 가장 간단한 절차는?
• 신규 사용자가 가질 수 잇는 가장 중요한 질문은?
• 사용자가 이 서비스로 할 수 있는 멋진 일은?

사용자에게 제품을 말로 알려주기만 하기보다는 제품을 직접 보여주는 것이 좋다.

예시: https://react.dev/learn#

 

4. CONCEPT 개념 문서

역할 : 사용자가 서비스 이면의 개념과 아이디어를 이해하는 데 도와주는 글

내용

• 서비스의 작동 원리. 단, 구현 세부 사항이 들어가지 않도록 해야 한다.

특징

• 짧고
• 간결하게

예시 : https://ko.vitejs.dev/guide/why.html
개념 문서 템플릿

첫번째 단락. 
문서에서 설명하는 개념을 소개  개요 개념이 어떻게 작동하는지에 대한 기술적 개요를 제시. 
하위 섹션에서 추가적인 하위 구성 요소나 관련된 개념을 설명  

관련 개념1  

관련 개념2  ...   

추가 자료 
개념을 구현하는 튜토리얼, How-to 가이드 등 관련된 문서의 나열

주의 사항

• 하나의 문서에서 설명하는 개념의 수를 제한하라.
• 서비스의 작동 원리. 단, 구현 세부 사항이 들어가지 않도록 해야 한다.

 

5. PROCESS 절차 문서

튜토리얼

• 사용자에게 특정 목표를 달성하는 방법을 가르쳐 주는 절차 문서.
• 문서가 너무 복잡한지, 단계가 많은지 파악하라. 서비스 자체를 개선할 수 있는 기회가 될 수 있다.

How-to 가이드

• 사용자가 서비스로 특정 단계를 수행함으로써 실제 비즈니스 문제를 해결하는 방법을 보여준다.
• 튜토리얼이 학습에 초점을 맞춘다면 How-to 가이드는 사용자가 실제 코드를 구현하는 동작에 기반을 둔다.

How-to 가이드 템플릿

첫 번째 단락에서는 핵심 개념을 소개하고 이 가이드에 필요한 포괄적인 정보를 제공한다.  
필수조건 
이 가이드에 있는 단계를 따라가기 전에 사용자가 해야 하는 일들의 목록을 재공한다.  
단계 
1 2 3 4 5 ...  

다음 단계 이 가이드에 있는 단계를 수행한 다음에 따라야 하는 추가 문서의 링크를 제공한다.

• 사용자의 니즈에 주의를 기울이고 사용자가 무슨 일을 하기를 원하는 지에 대한 회사의 전략을 이해해야 한다. 단, 유지 관리하는 데 수고가 많이 드니 주의 깊게 계획을 세우고 작성 대상을 잘 선정해야 한다.
• 사용자가 최대한 한 페이지에 머무르도록 하는 것이 가장 효과적이다.
• 문서 중간의 링크보다 끝에 추가 자료에 대한 링크를 제공하자.

 

6. REFERENCE 참조 문서

내용

• 어떤 동작이 어떤 결과를 낳는지, 즉 인과 관계를 다룬다.

API 레퍼런스

• 모든 리소스와 엔드포인트에 대한 상세한 참조 정보를 제공
• 풍부한 예제를 제공
• 상태 코드와 오류 메시지를 나열하고 정의
• 특징
  • 간결, 최소한의 설명
  • 소스 코드로부터 API 레퍼런스를 만들어보자.
• 예시: https://developers.kakao.com/docs/latest/ko/daum-search/dev-guide

용어집

• 특정 서비스, 분야 또는 산업에서 사용되는 용어와 정의를 모은 것
• 문서에서 동일한 용어가 서로 다른 의미로 정의되거나 같은 의미에 대해 서로 다른 용어를 사용하면 사용자에게 실망감을 준다.
• 외부 링크를 제한하자. 타 서비스의 용어를 사용하는 경우 특히 조심하자.
• 예시: https://developers.kakao.com/docs/latest/ko/documentation-guideline/glossary

문제 해결 문서

• 임시 대처법을 다양한 방식으로 문서화할 수 있다.
• 문제 발생 이유보다 해결 방법에 집중하자.
• 예시: https://ko.vitejs.dev/guide/troubleshooting.html

문제 해결 문서 템플릿

문제1 
설명: 
해결 단계: 
1 
2  

문제2 
설명: 
해결단계: 
1 
2

• 가능한 한 빨리 문제를 해결할 수 있도록 하자.
• 오류 메시지를 문서화하는 좋은 패턴은 같은 범주의 메시지들을 한 페이지에 그룹화

변경 사항 문서

내용

• 변경이 언제 일어났고 고객이 언제 영향을 받는지
• 이전에 지원되던 버전 및 통합 또는 지원 중단된 기능
• 파라미터나 중요한 필드의 이름 변경
• 옮겨진 오브젝트나 리소스
• 릴리스 노트
  • 새로운 기능
  • 버그 수정
  • 알려진 버그 또는 제약 사항
  • 단절적 변경 등 버전 마이그레이션 관련 사항

릴리스 노트 템플릿

YYYY-MM-DD 
항목 1 
- 요약 
- 영향 
- 이유 
- 필요한 조치 
항목 2   


YYYY-MM--DD ...

• 예시 : https://storybook.js.org/releases/7.6

✅문서화를 할 때

좋은 문서화 계획으로 얻을 수 있는 일

• 정보에 대한 사용자의 니즈를 예상하고 충족할 수 있다.
• 사용자와 내부 이해 관계자로부터 조기에 문서화 방향에 대한 피드백을 받을 수 있다.
• 문서뿐만 아니라 서버스에 대한 사용자 여정을 총체적으로 바라보고 빈큼과 부족한 점을 식별할 수 있다.
• 다른 이해 관계자와 문서 작성, 구조화, 배포 업무를 조율할 수 있다.

사용자에게 적합한 정보에 집중하자.

• 타깃 고객은 누구인가?
• 제품 출시를 통해 그들이 얻기를 바라는 가장 중요한 이점은 무엇인가?
• 중요도순으로 볼 때, 어떤 기능들을 출시할 것인가?
• 사용자가 제품 출시에서 기대하는 점은 무엇인가?
• 사용자가 제품이나 기능을 사용하기 전에 필요한 지식이 있는가?
• 어떤 유스 케이스들을 지원하는가?
• 사용자가 맞닥뜨릴 수 잇는 알려진 문제나 마찰 요소가 있는가?

✔️결론

팀 프로젝트를 하면서 가장 어려운 점이 정확한 의사소통인데, 문서화를 통해 이 부분을 어느 정도 해결할 수 있다고 생각합니다. 그렇지만 너무 문서화에만 집중해서 프로젝트의 진행도가 느려졌고, 그로 인해 초기 모델을 완성하지 못한 적이 있었습니다. 그래서 문서화를 어떻게 하면 최대한 가벼우면서도 정확한 내용을 담게 할 수 있을까 고민을 했고, 책을 읽으면서 그런 고민을 어느 정도 해소할 수 있었습니다. 이번 챕터에서 인상 깊었던 부분은 문서화의 시작은 사용자가 문서를 통해서 무엇을 얻을 수 있는지 정리한 내용이었습니다. 그리고 모든 프로젝트에서는 각각 필요한 문서 유형들이 있고, 모든 문서를 작성하지 않아도 된다는 점입니다. 문서를 통해서 사용자에게 무엇이 부족한지도 파악할 수 있도록 할 수 있어 필요할 때 문서화를 계획해서 채워나갈 수 있기 때문입니다. 항상 문서화하면 부담스럽게 여겨졌는데, 어떤 문서들이 필요한지, 어떤 내용으로 작성하는지 포괄적으로 알 수 있어서 좋았습니다.

이 글은 옵시디언을 통해 발행하였습니다.