명세·API 문서·릴리즈 노트를 Word로만 쓰면 diff·버전 관리가 어렵습니다. 블루버튼 마크다운 에디터로 팀 기술 문서 워크플로를 구축하는 방법입니다.
문서 유형별 템플릿
| 유형 | 필수 섹션 | 저장 위치 |
|---|---|---|
| API | Endpoint·Auth·Example | /docs/api |
| 명세 | In/Out·화면 | /docs/spec |
| 릴리즈 | Added/Fixed/Breaking | CHANGELOG.md |
팀 루틴
Markdown 규칙 (팀 합의)
- 제목은
##부터 (문서당#하나) - 표는 GitHub flavor
- 코드는 언어 태그 필수
팁: '문서 부채'는 명세와 코드 diff로 측정하세요. 마일스톤마다 md 1파일이라도 갱신하는 팀이 CR 분쟁이 적습니다.
CI 연동
PR에 docs/ 변경이 있으면 markdown lint + broken link check를 돌리세요. API 문서는 OpenAPI yaml과 md example response를 쌍으로 유지합니다.
버전 태그
릴리즈 v2.3.0마다 docs/releases/v2.3.0.md 한 파일 — CR과 릴리즈 노트를 연결하면 고객 커뮤가 쉬워집니다.
onboarding
신규 메이커에게 '첫 PR = docs typo fix 1건'을 과제로 주면, md workflow를 자연스럽게 학습합니다. 문서 culture는 작은 PR부터 시작할 때 유지됩니다.
docs PR template에 'related code PR link' checkbox를 넣으세요. code without doc·doc without code merge를 막는 simplest gate입니다.
weekly docs office hour 30분 — anyone can bring md PR for quick review. culture beats policy for documentation sustainability.
search: repo md full-text grep alias를 shell profile에 등록하면 onboarding dev가 docs discovery를 CLI habit으로 시작합니다.