고객에게 크고 복잡한 코드베이스를 인계하면서 축적된 역사와 미묘한 설계 이유까지 문서화했는데, Diátaxis가 탁월했음
필요한 문서 제목을 정하는 데는 시간이 걸렸지만, 유형이 정해지면 글의 목적과 어조가 명확해졌음. 참조 문서는 도표와 목록으로 기술하고, 사용법 안내서는 가르치기보다 정보를 전달하는 식으로 구분돼 일관되고 명료하게 작성하기 쉬웠음

이걸 읽고 나면 모든 문서가 결함투성이의 혼란스러운 구조로 보이기 시작하니 차라리 읽지 않는 편이 행복할 수도 있음

정말 그럴 수 있음. 창업자나 사용자 중심 관점보다 문서 담당자가 자기 일자리를 정당화하는 도구처럼 느껴지기도 함

상당한 시간을 들여 문서를 Diátaxis 구조로 개편했고 유용했지만, 이를 절대적인 규칙으로 받아들일 필요는 없음. 핵심은 각 콘텐츠가 네 가지 유형 중 하나에 속해야 한다는 것임
문서를 재구성하거나 다시 쓰려면 시작 전에 사이트 전체, 특히 복잡한 계층 구조를 읽기를 권함. 안내가 잘 쓰였고 개념이 반복돼 자연스럽게 체화하기 쉬움

그런데 “Start here” 첫 두 문장은 사이트 전체를 읽을 필요가 없으며 오히려 읽지 말라고 권함. 그럼에도 전부 먼저 읽으라고 권하는 이유가 궁금함

그 페이지는 마음에 들지 않아 삭제했으며 곧 사라질 예정임. 실제 문제를 충분히 다루지 못하고 있어 훨씬 나은 대안을 준비 중임

Diátaxis는 문서를 사고하고 작성하는 훌륭한 틀이지만, 최신 상태 유지가 어려움. 특히 튜토리얼과 참조 자료는 버전이 지정된 코드에서 자동 생성하지 않으면 시간이 지나며 실제 동작과 크게 어긋날 수 있음
Notion 위키의 검증 시각처럼 일정 기간이 지나면 소유자가 문서의 최신 여부를 다시 확인하게 하는 기능이 유용해 보임. 형식적으로 승인하기 쉽다는 약점이 있으므로, 철저한 감사 없이는 문서를 아예 비공개로 전환하는 방식도 고려할 만함

rustdoc, Documenter.jl, Sphinx도 지원하는 듯하지만, R에서는 Diátaxis의 세 범주가 패키지 구조와 잘 대응함
튜토리얼은 패키지 검증 시 실행되는 vignettes, 사용법 안내서는 기본적으로 실행 가능한 roxygen 문서 블록, 참조 문서는 roxygen이 주로 해석하는 TeX 또는 Markdown으로 구현할 수 있음. 다만 구현 근거를 문서화하는 표준 방식이 없고, 저장소 밖의 문서는 코드와 점차 어긋나기 쉬움

Python은 문서 사이트 전체를 버전별로 제공하는 점이 훌륭함. 예를 들어 2.7.18을 선택하면 튜토리얼까지 해당 버전의 문서를 볼 수 있음
개발 절차도 문서 갱신을 신중하게 다루며, 언어 기능을 추가하거나 변경하는 PEP에는 명시적인 How to Teach This 절까지 요구함

Diátaxis의 필요성을 느끼지 못했지만, 바이브 코딩 중 LLM에 do diataxis라고 지시해 제법 괜찮은 초안 문서를 얻기에는 편리함

현재 프로젝트 gcodepreview의 코드와 접근 방식을 정리하는 데 도움이 됐음
개요는 readme.md, 튜토리얼은 여러 템플릿 파일, 사용법 안내서는 문학적 프로그래밍 코드, 참조 문서는 색인과 명령어 용어집으로 나누는 구성이 자연스러워졌음

튜토리얼을 만들 때 에이전트에 스크린샷 디렉터리를 제공하고 절차를 말로 풀어준 뒤, 전체 내용을 안내서로 정리하게 하는 방식이 만족스러움