init: document-haness 하네스 설계
This commit is contained in:
DongHyeonka
@@ -0,0 +1,168 @@
|
||||
# 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 개수를 점수와 별도로 게이트한다.
|
||||
Reference in New Issue
Block a user