169 lines
6.6 KiB
Markdown
169 lines
6.6 KiB
Markdown
# Logic model for comprehensible technical documents
|
|
|
|
## 1. 문서는 질문 그래프다
|
|
|
|
좋은 기술 문서를 “서론-본론-결론”이라는 형식만으로 설명하면 부족하다. 실제 독자는 순차적으로 다음 질문을 해결한다.
|
|
|
|
```text
|
|
왜 읽어야 하는가?
|
|
↓
|
|
정확히 무엇을 다루는가?
|
|
↓
|
|
무엇을 이미 알아야 하는가?
|
|
↓
|
|
핵심 답 또는 결과는 무엇인가?
|
|
↓
|
|
그 답이 성립하는 이유와 메커니즘은 무엇인가?
|
|
↓
|
|
구체적인 사례에서 어떻게 보이는가?
|
|
↓
|
|
어떻게 확인하는가?
|
|
↓
|
|
언제 실패하거나 선택하지 않아야 하는가?
|
|
↓
|
|
그래서 무엇을 해야 하는가?
|
|
```
|
|
|
|
모든 문서가 이 질문을 동일한 비중으로 다루지는 않는다. 문서 유형은 **독자의 현재 상태와 목적**에 따라 필요한 질문 부분을 선택하고 순서를 최적화한 것이다.
|
|
|
|
## 2. 문서 유형을 섞을 때의 규칙
|
|
|
|
한 페이지에 여러 유형이 존재할 수 있지만 주된 목적은 하나여야 한다.
|
|
|
|
- Tutorial 안의 짧은 explanation은 현재 단계를 이해시키는 데 필요한 만큼만 둔다.
|
|
- How-to 안의 reference table은 절차 수행에 필요한 조회 표면으로 제한한다.
|
|
- Technical blog 안의 code example은 전체 API reference가 아니라 인과 관계를 보여준다.
|
|
- Reference 안의 장황한 배경 설명은 별도 explanation으로 분리한다.
|
|
- Troubleshooting 안의 fix는 확인된 cause branch에만 연결한다.
|
|
|
|
판정 질문:
|
|
|
|
> 이 부분이 독자의 현재 목표를 직접 전진시키는가, 아니면 다른 문서 유형의 목표를 새로 시작하는가?
|
|
|
|
후자라면 분리하거나 링크한다.
|
|
|
|
## 3. 논리 구조의 최소 단위
|
|
|
|
### Section contract
|
|
|
|
각 section은 다음을 가진다.
|
|
|
|
1. **Reader question**: 독자가 이 시점에 묻는 질문
|
|
2. **Purpose**: 이 절이 수행할 정보 작업
|
|
3. **Claim/answer**: 질문에 대한 명시적 답
|
|
4. **Support**: 근거, 메커니즘, 예시 또는 절차
|
|
5. **Boundary**: 답이 유효한 범위와 예외
|
|
6. **Transition**: 다음 질문이 왜 생기는지 연결
|
|
|
|
### Paragraph contract
|
|
|
|
문단은 보통 다음 순서를 사용한다.
|
|
|
|
```text
|
|
중심 문장 → 이유/근거 → 구체화/예시 → 다음 문장으로의 연결
|
|
```
|
|
|
|
문단이 두 개의 독립 결론을 갖거나, 첫 문장이 뒤의 내용을 예고하지 못하거나, 마지막 문장이 새 주제를 시작하면 분리 후보로 본다.
|
|
|
|
## 4. 이해를 돕는 인과 구조
|
|
|
|
기술 설명에서 목록만 나열하면 독자는 구성요소를 기억해도 시스템을 예측하지 못한다. 메커니즘 section은 다음 중 하나의 명시적 순서를 사용한다.
|
|
|
|
- 시간: 요청 전 → 요청 중 → 응답 후
|
|
- 데이터 흐름: 입력 → 변환 → 저장 → 출력
|
|
- 제어 흐름: 조건 → 분기 → 행동 → 상태 전이
|
|
- 장애 흐름: 트리거 → 증상 → 전파 → 완화 → 복구
|
|
- 결정 흐름: 제약 → 비교 기준 → 대안 평가 → 선택 → 수용 비용
|
|
|
|
각 화살표에는 “왜 다음 상태가 되는가”가 있어야 한다. 단순히 컴포넌트 이름을 이어 붙이지 않는다.
|
|
|
|
## 5. 점진 공개
|
|
|
|
독자가 세부사항을 이해하기 위한 구조를 먼저 제공한다.
|
|
|
|
1. 핵심 답/결과
|
|
2. 범위와 전제
|
|
3. 가장 단순한 모델
|
|
4. 정상 메커니즘
|
|
5. 완주하는 예시
|
|
6. 검증
|
|
7. 예외·실패·트레이드오프
|
|
8. 운영 세부사항
|
|
|
|
예외를 너무 일찍 넣으면 기본 모델을 형성하기 어렵고, 너무 늦게 숨기면 과도한 확신을 준다. 기본 모델을 제시한 직후 “어디까지 유효한가”를 명시하고, 상세 예외는 뒤에서 확장한다.
|
|
|
|
## 6. Worked example 계약
|
|
|
|
예시는 코드 조각의 존재가 아니라 **시작 상태부터 검증 결과까지의 연결**이다.
|
|
|
|
필수 요소:
|
|
|
|
- 초기 상태와 입력
|
|
- 각 단계의 행동 또는 상태 변화
|
|
- 단계의 이유
|
|
- 예상 관측
|
|
- 최종 결과
|
|
- 성공 기준
|
|
- 실패했을 때 되돌아갈 지점
|
|
|
|
초보 독자에게는 중간 추론을 더 많이 보이고, 숙련 독자용 문서에서는 자명한 단계를 줄인다. 브리프의 `prior_knowledge`가 이 깊이를 결정한다.
|
|
|
|
## 7. 근거와 주장 수준
|
|
|
|
문장은 다음 네 종류 중 하나로 분류할 수 있어야 한다.
|
|
|
|
| 종류 | 예 | 처리 |
|
|
|---|---|---|
|
|
| 관측 사실 | 특정 로그가 발생했다 | 출처·실험·측정 연결 |
|
|
| 일반 기술 사실 | 프로토콜 의미, API 계약 | 권위 있는 reference 연결 |
|
|
| 가정/가상 예시 | 설명을 위한 단순 모델 | 가정/예시임을 표시 |
|
|
| 권고/판단 | 이 조건에서는 A를 선택 | 기준·대안·비용을 공개 |
|
|
|
|
“관련된 출처”와 “그 주장을 지지하는 출처”는 다르다. Source pack의 `facts`는 허용된 주장 범위를 줄이는 역할을 한다.
|
|
|
|
## 8. 트레이드오프 구조
|
|
|
|
좋은 기술 글은 선택을 미화하지 않는다.
|
|
|
|
```text
|
|
선택한 접근
|
|
├── 얻는 것
|
|
├── 지불하는 비용
|
|
├── 대안
|
|
├── 선택 기준
|
|
├── 실패 조건
|
|
└── 선택하지 말아야 하는 상황
|
|
```
|
|
|
|
대안을 비교할 때는 같은 기준을 사용한다. 한 대안은 성능으로, 다른 대안은 구현 편의성으로만 설명하면 비교가 성립하지 않는다.
|
|
|
|
## 9. 절차 안전성
|
|
|
|
절차 문서의 단계는 다음 상태 머신으로 본다.
|
|
|
|
```text
|
|
PRECONDITION_CHECKED
|
|
→ CHECKPOINT_CREATED
|
|
→ CHANGE_APPLIED
|
|
→ EXPECTED_RESULT_OBSERVED
|
|
→ VERIFIED
|
|
```
|
|
|
|
어느 단계에서든 불일치하면 다음으로 진행하지 않고 `STOPPED → ROLLED_BACK → RECOVERY_VERIFIED`로 이동해야 한다. 파괴적 명령은 경고 문구만으로 충분하지 않으며 백업/복구점, 영향 범위, 확인 명령이 함께 있어야 한다.
|
|
|
|
## 10. 품질 평가 차원
|
|
|
|
모델 reviewer는 다음 차원을 각각 검사한다.
|
|
|
|
- `reader_goal_alignment`: 약속한 결과를 실제로 제공하는가
|
|
- `information_architecture`: 문서 유형과 section 역할이 맞는가
|
|
- `logical_flow`: 전제·인과·결론·전환이 끊기지 않는가
|
|
- `cognitive_load`: 선행지식에 맞고 세부사항이 점진적으로 공개되는가
|
|
- `evidence_traceability`: 확인 가능한 주장이 근거와 연결되는가
|
|
- `example_verifiability`: 예시가 끝까지 실행·검증 가능한가
|
|
- `scannability`: heading과 첫 문장만 읽어도 구조가 보이는가
|
|
- `operational_safety`: 절차·변경·실패·복구가 안전한가
|
|
- `completeness_and_limits`: 범위, 비범위, 예외, 트레이드오프가 있는가
|
|
|
|
한 차원의 평균이 전체 결함을 숨기지 않도록 blocker/error 개수를 점수와 별도로 게이트한다.
|