개발 문서 잘쓰기 실전 가이드

목적: 독자가 바로 이해하고 바로 실행할 수 있는 문서를 만드는 실무 가이드

0. 이 문서로 얻는 것

문서의 유형을 한 가지로 선택할 수 있다.
독자/목표/성공 기준을 문서 초반에 배치할 수 있다.
유형별 템플릿으로 동일한 형식의 구조를 유지할 수 있다.
리뷰 시점에 체크리스트로 품질 이슈를 줄일 수 있다.

핵심 원칙

독자 중심으로 쓴다.
현재 시제와 능동태를 기본으로 쓴다.
실행 가능한 문장으로 쓴다.
헤딩·링크·예시는 검색과 접근성을 고려한다.

1. 문서 유형을 먼저 고르기

1.1 왜 먼저 고치지 말고 먼저 정해야 하나?

문서 유형이 다르면 같은 내용도 구조와 톤이 달라져야 합니다. 유형이 섞이면 읽는 속도도 낮아지고, 리뷰 포인트도 흐려집니다.

독자의 현재 목표가 무엇인가요?
가장 먼저 달성하고 싶은 결과는 무엇인가요?
성공 기준을 어떻게 검증하나요?

1.2 문서 유형 결정 기준

튜토리얼: 처음 배우며 따라 하는 가이드
How-to: 당장 문제를 해결해야 하는 작업
레퍼런스: 정확한 규격·사양 조회
설명: 개념/원리/배경 이해
README: 방문자용 첫인상 소개
설계서: 팀 합의·리뷰용 제안 문서
ADR: 결정 배경과 영향 기록
안내문/알림: 대상자와 실행 항목을 빠르게 전달

2. 문서 유형별 템플릿(최소 형식)

2.1 튜토리얼

markdown

# <튜토리얼 제목: 무엇을 만들지>

## 이 튜토리얼에서 얻는 결과
- 완료 기준(정량):

## 준비물
- 계정/권한
- 설치 항목
- 소요 시간

## 단계
1. 행동
   - 왜 하는지
   - 예상 출력/검증 방법

## 마무리
- 무엇을 완료했는지
- 다음 할 일

2.2 How-to

markdown

# <문제 해결 제목>

## 목표

## 전제 조건

## 절차
1. 단계
   - 실행
   - 결과 확인

## 검증

## 트러블슈팅

2.3 레퍼런스

markdown

# <대상 엔드포인트/명령어/개념명>

## 개요

## 항목
- 파라미터
- 반환값
- 오류 코드

## 사용 예시

## 제약 및 버전

2.4 설명

markdown

# <개념 제목>

## 한 줄 요약

## 배경

## 원리

## 트레이드오프

## 관련 링크

2.5 README

markdown

# <프로젝트명>

## 무엇인가요

## 빠른 시작

## 사용법

## 기여/개발

## 도움받기

2.6 설계서

markdown

# <설계서 제목>

## Context
## Goals / Non-goals
## 제안 설계
## 대안 비교
## 롤아웃/리스크

2.7 ADR

markdown

# ADR-<번호>: <결정 제목>

## Context
## Decision
## Consequences

2.8 안내문

markdown

제목: [핵심 요약]

안녕하세요.

1. 결론: 무엇이 바뀌는지
2. 영향: 누구에게/무엇을/언제까지
3. 상세: 배경/이유/예외
4. 문의: 채널

3. 문체/어조/용어 규칙

3.1 독자에게 직접 말하기

“우리는 합니다”보다 “당신은 이렇게 합니다”가 더 명확합니다.
비난/비하/조롱 표현은 피합니다.
문장을 짧게 나누어 한 번에 한 행동만 지시합니다.

3.2 2인칭, 현재 시제, 능동태

기본은 ~합니다, ~하세요 형태로 씁니다.
가능하면 과거 완료보다 현재 진행/현재 시제를 사용합니다.
주어를 생략하지 말고 책임자를 명확히 씁니다.

3.3 용어 관리

전문 용어는 처음 한 번 정의 후 유지합니다.
같은 약어를 문서 중간에 다른 의미로 바꾸지 않습니다.
외래어는 쉬운 대응어가 있으면 병기합니다.

4. 가독성

4.1 한 문단 한 주제

한 문단은 한 주제만 유지합니다.
문장이 길면 문장 단위를 나눕니다.
조건은 지시문 앞에 둡니다.

4.2 목록 사용 규칙

순서가 중요: 번호 목록
중요도/특징/주의: 불릿 목록
두 개 이상의 비교 항목: 표

4.3 헤딩 규칙

제목은 고유하고 설명적으로 씁니다.
계층은 불필요하게 생략하지 않고 2~3단계로 제한합니다.
동일 제목이 반복되면 병합하거나 재정의합니다.

5. 링크/접근성/국제화

5.1 링크 텍스트

“여기”, “클릭” 같은 텍스트는 피합니다.
링크는 목적을 드러내는 문장으로 씁니다.
- 나쁜 예: 자세한 내용은 여기
- 좋은 예: OAuth 설정 가이드 보기

5.2 코드/명령 예시

언어 표시를 꼭 지정합니다.

bash

# 실행 가능한 예시
npm run lint

5.3 이미지·다이어그램

시각 요소에만 의존하지 말고 핵심 내용을 텍스트로 보강합니다.
삽입 이미지는 설명이 있으면 대체 텍스트를 함께 둡니다.

5.4 번역 친화성

날짜/시간/단위는 모호하지 않게 씁니다.
비유/은어/관용구를 줄이고 명확한 동사를 사용합니다.

6. 문서 초안 품질 점검 루틴

flowchart TD
  A[문서 초안 작성] --> B[유형 1개로 고정]
  B --> C[목표/독자/성공 기준 확인]
  C --> D[구조 점검]
  D --> E[링크/표현/코드 블록 점검]
  E --> F[리뷰 체크리스트 적용]
  F --> G[배포/공유]
  G --> H[피드백 반영]

6.1 작성 체크리스트

[ ] 문서 유형이 명확한가?
[ ] 독자/목표/성공 기준이 초반에 있는가?
[ ] 제목과 헤딩이 설명적인가?
[ ] 용어·약어가 일관적인가?
[ ] 번호 목록과 불릿의 사용이 적절한가?
[ ] 코드 블록에 언어가 지정되었는가?
[ ] 링크 텍스트가 목적을 설명하는가?
[ ] 실행 결과/검증 방법이 있는가?
[ ] 이미지/도식은 텍스트 요약이 있는가?

6.2 리뷰 체크리스트

[ ] 문서 유형 혼합이 과도하지 않은가?
[ ] 편집/재배치해도 구조가 유지되는가?
[ ] 편견적·군사적 은유 표현이 없는가?
[ ] 독자가 바로 따라 할 수 있는 문장 위주인가?
[ ] 접근성 항목이 빠지지 않았는가?

7. 자주 하는 잘못과 바르게 쓰는 방법

상황	문제 문장	개선 문장	개선 포인트
단계 서술	아래 명령을 실행하면 됩니다.	터미널에서 `make test`를 실행하세요. PASS면 다음 단계로 진행합니다.	행동+검증을 함께 제시
조건 위치	파일을 수정하고 권한이 없으면 요청하세요.	권한이 없다면 먼저 요청한 뒤 파일을 수정하세요.	조건을 지시문 앞에 둠
링크 텍스트	자세한 내용은 여기	자세한 내용은 OAuth 설정 가이드에서 확인	링크 목적 자체를 설명
에러 피드백	잘못 입력했습니다. 다시 하세요	입력 형식이 `YYYY-MM-DD`인지 확인하세요.	사용자 탓보다 해결 동작 제시

8. 끝맺음

이 문서는 글의 “형태(유형)”를 먼저 정하고, “내용(목표)”을 중심으로 구성합니다.
앞으로는 문서마다 위 체크리스트를 통일해 팀 전체 품질 편차를 줄입니다.