9.7 KiB
9.7 KiB
조사 출처와 하네스 적용 매트릭스
조사·접근일: 2026-07-23
선택 기준: 공식 지침, 표준, 원 논문, 또는 실제 기술 조직이 발행한 엔지니어링 글
이 표는 출처 내용을 그대로 규칙으로 복제한 것이 아니라, 반복되는 원칙을 ClariDoc의 계약·구조·검사로 번역한 기록이다.
| ID | 출처 | 유형 | 핵심 관찰 | ClariDoc 적용 | 주의점 |
|---|---|---|---|---|---|
| R01 | Google developer documentation style guide | 공식 편집 지침 | 기술 독자에게 명확하고 일관되게 쓰되 프로젝트별 스타일을 우선하고, 규칙보다 실제 독자 명확성을 우선한다. | 브리프의 tone, 프로젝트 규칙 우선 원칙, 일관성 중심 lint |
스타일 지침은 정보 구조 전체를 대신하지 않는다. |
| R02 | Google Technical Writing: Documents | 공식 교육 자료 | 범위와 비범위, 대상 독자와 사전지식, 시작부 핵심 요약, 익숙한 것과의 연결, 독자 요구에 따른 조직을 권한다. | scope, non_scope, audience, prior_knowledge, core_message, mental_model |
입문 교육 자료이므로 고위험 운영 문서의 모든 요구를 다루지는 않는다. |
| R03 | Google Technical Writing One summary | 공식 교육 자료 | 문단 첫 문장에 중심점을 두고 한 문단은 한 주제에 집중하며, 문서 시작에서 범위·독자·핵심점을 제시한다. | 장문 문단/문장 lint, 오프닝 계약, one-question-per-section | 언어별 문장 길이 기준은 휴리스틱으로 조정해야 한다. |
| R04 | Google Technical Writing: Organizing large documents | 공식 교육 자료 | outline과 계층형 heading, 관련 주제의 묶음, 점진적 공개가 긴 문서 탐색과 이해를 돕는다. | outline 선행, heading 계층 검사, progressive disclosure prompt | 짧은 글에는 과도한 계층이 오히려 방해가 될 수 있다. |
| R05 | GitHub Docs best practices | 공식 콘텐츠 설계 지침 | 독자·목적·콘텐츠 유형을 먼저 정하고, 중요도와 사용 순서로 조직하며, 한 문장/문단 한 생각, 결론 우선, 점진적 상세화, 의미 있는 소제목을 사용한다. | Brief, DocumentType, 구조 계약, 제목·문단 lint, answer-first prompt |
GitHub 제품 문맥의 예시는 일반화할 때 조정이 필요하다. |
| R06 | GitHub Docs content design principles | 공식 콘텐츠 원칙 | 사용자 목표, 고가치 시나리오, “필요한 만큼만”, 명확성·의미·정확성·일관성을 우선한다. | reader_goal, scope/non-scope, 불필요 섹션 억제, quality gate |
“충분한 문서량”은 조직과 위험도에 따라 달라진다. |
| R07 | Diátaxis | 문서 아키텍처 프레임워크 | 튜토리얼, 하우투, 참조, 설명은 서로 다른 사용자 요구와 작성 방식을 가진다. | 네 기본 유형을 중심으로 DocumentType 설계 |
기술 블로그·트러블슈팅·설계 문서는 별도 실무 패턴을 추가했다. |
| R08 | OASIS DITA technical content elements | 표준 | Concept, Task, Reference, Troubleshooting을 분리한다. Task는 context, prerequisites, steps, expected result, example, next steps 구조를 가진다. | 절차형 구조와 트러블슈팅 유형, prerequisites/verification/next steps | DITA XML 요소를 구현한 것이 아니라 정보 유형만 참고했다. |
| R09 | Kubernetes page content types | 대규모 오픈소스 공식 지침 | Concept, Task, Tutorial, Reference별로 overview, prerequisites, steps, objectives, cleanup, examples 등의 권장 섹션이 다르다. | tutorial/how-to/reference 섹션 계약, cleanup/rollback, next steps | Kubernetes 사이트 템플릿 자체는 ClariDoc에 복제하지 않았다. |
| R10 | Microsoft Writing Style Guide | 공식 편집 지침 | 기술 내용을 단순하고 직접적이며 명확한 언어로 전달한다. | 전문적이고 직접적인 기본 tone, 간결성 lint/review | 브랜드 보이스는 프로젝트별로 달라질 수 있다. |
| R11 | Microsoft: Writing for all abilities | 공식 접근성 지침 | heading level로 계층을 전달하고, 목록·표·제목으로 관계를 강화하며, 위치만 가리키는 표현을 피한다. | heading-level 검사, scan surface, 의미 있는 제목 | 접근성 전체 표준을 구현한 것은 아니다. |
| R12 | Sweller & Cooper, 1985, worked examples | 원 연구 | 초보 학습에서 완성된 해결 과정을 연구 대상으로 삼아 worked example의 학습 효과를 보였다. | 시작 상태부터 결과까지 이어지는 worked_example, checkpoint |
대수 학습 결과를 모든 기술 문서에 직접 일반화하지 않는다. 설계 가설로 사용한다. |
| R13 | Mautone & Mayer, 2001, signaling | 원 연구 | 요약, section heading, 인과 연결어 등 구조 신호가 설명의 조직을 드러내고 전이 수행에 영향을 주었다. | reader question, meaningful heading, transition, causal chain | 멀티미디어 학습 실험이며 실제 개발자 문서와 독자군이 다르다. |
| R14 | Netflix: In-House LLM Serving at Netflix | 실제 엔지니어링 글 | 글의 초점과 대안을 먼저 밝히고, 아키텍처 개요 뒤에 의존 순서의 설계 결정, 운영에서 드러난 문제를 설명한다. | 기술 블로그의 promise → architecture → decisions → operational evidence → lessons 흐름 | 단일 최신 표본이며 Netflix 전체 글의 대표라고 볼 수 없다. |
| R15 | Cloudflare: Building Jetflow | 실제 엔지니어링 글 | 문제와 프레임워크 구조, 구체적 데이터베이스 사례, 성능·편의성의 트레이드오프와 교훈을 연결한다. | mechanism, worked example, evidence, tradeoffs | 제품·워크로드 특화 선택을 일반 처방으로 사용하지 않는다. |
| R16 | Dropbox: Feature store powering real-time AI | 실제 엔지니어링 글 | 왜 기존 해법이 맞지 않았는지, 목표·요구사항, 설계, 속도·규모·신선도, 트레이드오프와 교훈을 예고한다. | context/constraints → goals → mechanism → evidence → lessons | 회사 블로그는 논문식 검증이 아니라 실무 설명이다. |
| R17 | AWS Builders’ Library: Making retries safe with idempotent APIs | 실제 설계 설명 | 단순화된 가정을 먼저 드러내고, timeout으로 상태가 불명확해지는 구체적 시나리오를 통해 부작용과 설계 원리를 설명한다. | 가정·실패 조건·worked scenario·reconciliation을 기술 블로그 구조에 반영 | 특정 AWS 설계 경험이며 모든 API에 동일하게 적용되지 않는다. |
| R18 | AWS Builders’ Library: Timeouts, retries, and backoff with jitter | 실제 운영 설명 | 재시도·timeout의 위험, 멱등성, backoff/jitter, 부하 증폭과 같은 운영 메커니즘을 실패 관점에서 연결한다. | 예제 source pack, mechanism/failure/tradeoff/verification 구조 | 시점과 서비스 맥락을 본문에 명시해야 한다. |
반복 패턴과 구현 위치
| 반복 패턴 | 구현 위치 |
|---|---|
| 독자와 과업을 먼저 정의 | src/claridoc/models.py의 Audience, Brief |
| 유형별로 정보 요구를 분리 | DocumentType, src/claridoc/structures.py |
| 범위·비범위·버전·선행조건 | Brief, Constraints, opening lint |
| 결론 우선과 점진적 상세화 | STRUCTURE_SPECS, src/claridoc/prompts.py |
| 섹션별 질문·목적·전환 | OutlineSection |
| 예시와 체크포인트 | worked_example, checkpoint, type-specific lint |
| 절차의 검증·복구 | verification, rollback, SAFE001 |
| 출처 단위 추적 | SourcePack, EVD001–EVD006 |
| 대안·트레이드오프·한계 | 유형 계약, TYPE006 |
| 작성자와 검토자 역할 분리 | PipelineConfig.reviewers, provider adapters |
| 결정적 검사 + 모델 판단 | lint_document, composite quality gate |
| 재현과 감사 | raw responses, events, rounds, manifest.json |
해석 원칙
- 여러 출처에 반복되는 원칙은 기본값으로 채택했다.
- 특정 조직에만 해당하는 스타일은 계약이 아니라 예시로 남겼다.
- 인지 연구 결과는 직접적인 제품 품질 보증이 아니라 구조 설계의 근거로 제한했다.
- 실제 엔지니어링 글의 패턴은 관찰적 추론이며, 글의 목적에 따라 순서를 변경할 수 있다.
- 프로젝트별 스타일, 독자 조사, 실제 오류 데이터가 있으면 이 일반 매트릭스보다 우선한다.