document-haness/docs/LOGIC_MODEL.md

Logic model for comprehensible technical documents

1. 문서는 질문 그래프다

좋은 기술 문서를 “서론-본론-결론”이라는 형식만으로 설명하면 부족하다. 실제 독자는 순차적으로 다음 질문을 해결한다.

왜 읽어야 하는가?
  ↓
정확히 무엇을 다루는가?
  ↓
무엇을 이미 알아야 하는가?
  ↓
핵심 답 또는 결과는 무엇인가?
  ↓
그 답이 성립하는 이유와 메커니즘은 무엇인가?
  ↓
구체적인 사례에서 어떻게 보이는가?
  ↓
어떻게 확인하는가?
  ↓
언제 실패하거나 선택하지 않아야 하는가?
  ↓
그래서 무엇을 해야 하는가?

모든 문서가 이 질문을 동일한 비중으로 다루지는 않는다. 문서 유형은 독자의 현재 상태와 목적에 따라 필요한 질문 부분을 선택하고 순서를 최적화한 것이다.

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

문단은 보통 다음 순서를 사용한다.

중심 문장 → 이유/근거 → 구체화/예시 → 다음 문장으로의 연결

문단이 두 개의 독립 결론을 갖거나, 첫 문장이 뒤의 내용을 예고하지 못하거나, 마지막 문장이 새 주제를 시작하면 분리 후보로 본다.

4. 이해를 돕는 인과 구조

기술 설명에서 목록만 나열하면 독자는 구성요소를 기억해도 시스템을 예측하지 못한다. 메커니즘 section은 다음 중 하나의 명시적 순서를 사용한다.

• 시간: 요청 전 → 요청 중 → 응답 후
• 데이터 흐름: 입력 → 변환 → 저장 → 출력
• 제어 흐름: 조건 → 분기 → 행동 → 상태 전이
• 장애 흐름: 트리거 → 증상 → 전파 → 완화 → 복구
• 결정 흐름: 제약 → 비교 기준 → 대안 평가 → 선택 → 수용 비용

각 화살표에는 “왜 다음 상태가 되는가”가 있어야 한다. 단순히 컴포넌트 이름을 이어 붙이지 않는다.

5. 점진 공개

독자가 세부사항을 이해하기 위한 구조를 먼저 제공한다.

1. 핵심 답/결과
2. 범위와 전제
3. 가장 단순한 모델
4. 정상 메커니즘
5. 완주하는 예시
6. 검증
7. 예외·실패·트레이드오프
8. 운영 세부사항

예외를 너무 일찍 넣으면 기본 모델을 형성하기 어렵고, 너무 늦게 숨기면 과도한 확신을 준다. 기본 모델을 제시한 직후 “어디까지 유효한가”를 명시하고, 상세 예외는 뒤에서 확장한다.

6. Worked example 계약

예시는 코드 조각의 존재가 아니라 시작 상태부터 검증 결과까지의 연결이다.

필수 요소:

• 초기 상태와 입력
• 각 단계의 행동 또는 상태 변화
• 단계의 이유
• 예상 관측
• 최종 결과
• 성공 기준
• 실패했을 때 되돌아갈 지점

초보 독자에게는 중간 추론을 더 많이 보이고, 숙련 독자용 문서에서는 자명한 단계를 줄인다. 브리프의 prior_knowledge가 이 깊이를 결정한다.

7. 근거와 주장 수준

문장은 다음 네 종류 중 하나로 분류할 수 있어야 한다.

종류	예	처리
관측 사실	특정 로그가 발생했다	출처·실험·측정 연결
일반 기술 사실	프로토콜 의미, API 계약	권위 있는 reference 연결
가정/가상 예시	설명을 위한 단순 모델	가정/예시임을 표시
권고/판단	이 조건에서는 A를 선택	기준·대안·비용을 공개

“관련된 출처”와 “그 주장을 지지하는 출처”는 다르다. Source pack의 facts는 허용된 주장 범위를 줄이는 역할을 한다.

8. 트레이드오프 구조

좋은 기술 글은 선택을 미화하지 않는다.

선택한 접근
├── 얻는 것
├── 지불하는 비용
├── 대안
├── 선택 기준
├── 실패 조건
└── 선택하지 말아야 하는 상황

대안을 비교할 때는 같은 기준을 사용한다. 한 대안은 성능으로, 다른 대안은 구현 편의성으로만 설명하면 비교가 성립하지 않는다.

9. 절차 안전성

절차 문서의 단계는 다음 상태 머신으로 본다.

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 개수를 점수와 별도로 게이트한다.