Sg Write Docs

독자와 메시지에 맞는 글 작성

전달할 메시지와 독자가 얻으려는 것을 연결한다. 읽을 이유를 서두에서 드러내고 본문에서 그 기대를 충족한다. 기대 변화는 이해·판단·태도·행동일 수 있으며 모든 글에 행동 촉구를 요구하지 않는다.

시작과 대화

1. 새 글 작성, 기존 글 재구성, 검토, 독자 프로필 작업 중 요청을 구분한다. 검토만 요청받았으면 파일을 수정하지 않는다. 독자 프로필만 다루는 요청은 아래 독자 구성 절차로 진행하며 특정 글의 메시지·frontmatter 작성을 요구하지 않는다.
2. 기존 대화와 자료에서 작성 의도, 독자의 필요, 매체·장르·분량 제약을 읽는다. 대상 프로젝트의 문체, 메타데이터, 독자 자료, 인용과 렌더링 관례도 확인한다.
3. 작성 대화와 메타데이터 가이드를 읽고 핵심 메시지, 기대 변화, 주 독자와 필요를 정리한다. 빠지거나 상충하는 핵심은 완성 원고 작성 전에 반드시 대화로 좁힌다. 이미 드러난 답은 재질문하지 않는다.
4. 추상적인 답에는 구체적인 후보나 대비되는 예시로 응답을 돕고, 한 번에 하나의 중요한 선택을 묻는다. 사용자의 답을 짧게 되짚어 작성 결정에 반영하며 별도 승인 절차로 만들지 않는다.
5. 핵심 네 항목이 명확하고 구조를 바꿀 충돌이 해소되면 질문을 마친다. 질문 생략이나 판단 위임을 명시했으면 가정을 밝히고 진행한다. 무응답을 동의로 간주하지 않는다.
6. 작성·재구성에서는 문서별 의도와 독자 정보를 간결한 writing frontmatter로 남긴다. 기존 동등 필드는 재사용한다. 검토에서는 이 정보를 검토 기준으로만 구성한다.

독자 구성

1. 사용자가 지정한 독자와 프로필, 프로젝트 관례와 docs/audiences/를 차례로 확인한다. 이번 글의 독자 정보는 작성 대화와 메타데이터 가이드에 따라 기록한다.
2. 주 독자 한 명 또는 역할 집단을 선택한다. 부 독자는 같은 필요와 흐름을 공유할 때 고려한다. 목적·책임·사전지식이 충돌하면 우선순위를 질문하고 분리나 별도 진입점을 제안한다.
3. 작성 결정을 바꾸는 상황, 관심·우려, 공통 기반, 지식 격차와 제약만 사용한다. 직함이나 단일 숙련도 등급으로 주제별 지식 상태를 대신하지 않는다.
4. 작성자가 원하는 반응과 독자가 실제로 필요로 하는 것을 구별한다. 독자에 관한 확인·추론·미확인을 구분하고 근거 없는 감정이나 취향을 사실로 만들지 않는다.
5. 재사용 프로필을 다루거나 문서별 지식 격차·개념 연결을 설계할 때 독자 모델링 가이드를 읽는다. 현재 요청은 문서별 조건에 반영하며, 기존 프로필의 변경은 갱신 후보로 보고한다.

재사용 프로필은 사용자가 요청하거나 저장을 승인했을 때만 독자 프로필 템플릿을 참고해 만든다. 문서별 frontmatter 기록과 재사용 프로필의 생성·갱신을 혼동하지 않는다.

장르와 근거

1. 매체와 장르의 관례에 맞춰 글의 형식을 정한다. 보고서·블로그·기사·논문을 Diátaxis에 억지로 분류하지 않는다.
2. 기술·제품 문서의 유형을 정하거나 혼합 문서를 재구성할 때 문서 유형 가이드를 읽고 튜토리얼·방법 안내서·참조·설명을 선택한다. 네 유형 세트나 폴더를 강제로 만들지 않는다.
3. 사실 주장을 원천과 대조해 확인·추론·미확인을 구분한다. 의견, 해석과 기대를 관찰 결과처럼 쓰지 않는다. 근거가 부족하면 주장 범위를 좁히거나 미확인 내용과 필요한 자료를 밝힌다.
4. 코드·제품 동작을 설명할 때는 설정, 스키마, 테스트와 실행 결과를 대조하고 적용 revision·환경을 확인한다. 의도·구현·관찰을 서로 대체하지 않는다.
5. 기존 역공학 산출물이 있으면 관련 claim과 근거를 소비하되 필수 선행 단계로 만들지 않는다. 근거 선택, 보수적 재구성, 실행 검증이나 품질 리뷰에서는 근거와 검토 가이드를 읽는다.
6. 출처는 매체·투고처·프로젝트의 인용 관례를 따른다. 별도 관례가 없는 기술 문서는 번호 인용을 기본으로 하고, 일반 글은 의미 있는 출처 링크를 기본으로 한다. 번호 인용을 새로 만들거나 검토할 때 근거 인용 가이드를 읽는다.
7. 본문에 모든 내부 추적 정보를 노출하지 않는다. 비밀값, 개인정보, 내부 업무 데이터와 원시 독자 대화는 문서나 메타데이터로 옮기지 않는다.

서두·본문·결론 작성

작성·재구성·검토에서는 서두와 진입 요약 가이드를 읽는다.

1. 메시지·독자 정보에서 제목과 서두가 답할 질문, 본문이 제공할 근거·경험, 기대 변화를 연결한다. 같은 정보를 문서 계약이나 별도 브리프로 중복 저장하지 않는다.
2. 명시된 분량·매체 제약을 우선하고 독자의 지식 격차와 기대 변화에서 전체 분량, 설명 깊이, 사례·근거의 배치와 용어 도입을 도출한다. 작성 전략 전체를 frontmatter 필수 항목으로 늘리지 않는다.
3. 서두 초안으로 읽을 이유와 흐름을 잡는다. 제목, 첫 문단, 요약, 초록, 서론의 역할을 장르에 맞춰 구분하며 독립 요약이나 고정 정보 순서를 강제하지 않는다.
4. 확인된 관심·우려와 글의 목적에 맞춰 공감·긴장·안도·성찰 등의 정서적 표현을 선택한다. 목적에 기여하는 일화와 질문은 허용하되 과장이나 근거 없는 약속으로 주목을 끌지 않는다.
5. 낯선 필수 용어는 필요한 지점에서 공통 기반과 연결해 설명한다. 익숙한 전문 용어를 불필요하게 풀거나, 쉽게 쓰기 위해 정확성·위험·제한을 제거하지 않는다.
6. 기술적 구조·흐름·상태 변화가 핵심이면 시각 설명 가이드를 읽고 도식이 글보다 이해 부담을 줄이는지 판단한다. 개념 연결이 필요하면 대응 관계와 비유의 한계를 밝힌다.
7. 본문은 서두가 약속한 답과 근거를 제공한다. 다른 문서 링크는 세부 근거와 후속 탐색에 사용하며 주된 질문의 답을 외부 문서로 떠넘기지 않는다.
8. 결론이 필요한 글에서는 본문이 뒷받침한 메시지를 기대 변화와 연결한다. 본문을 그대로 반복하거나 새 주장을 넣지 않고, 다음 행동이나 성찰은 목적에 맞을 때 제시한다.
9. 본문의 사실·결론·범위가 안정되면 서두와 frontmatter를 다시 대조해 완성한다. 기존 문서는 인간 서술, 유효한 링크, 메타데이터와 정보 구조를 보존하며 요청 범위만 수정한다.
10. 튜토리얼이나 명시적인 숙련 설계 요청에서만 변형 연습, 줄어드는 힌트와 독립 수행 확인을 추가한다.

검증과 보고

1. 대화에서 확인한 메시지·기대 변화·독자·필요가 frontmatter, 서두, 본문과 결론에 일관되게 반영됐는지 확인한다. 서두가 약속한 가치와 사실을 본문에서 실제로 찾을 수 있어야 한다.
2. 독자 정보가 분량·내용·순서·표현·용어·안내 중 실제 작성 결정으로 이어지는지 확인한다. 근거 없는 추정이 확인된 특성으로 바뀌지 않았는지 점검한다.
3. 장르와 명시된 분량 제약에 맞고, 관심을 끌기 위해 결과·위험·불확실성을 숨기거나 과장하지 않았는지 검토한다. 모든 글에 동일한 서두 형식이나 읽기 시간 상한을 적용하지 않는다.
4. 사실, 출처, 링크, 경로, 전제조건과 완료 조건을 확인한다. 기술 문서에서는 revision·환경과 예제 출력을 대조하고 참조 항목의 누락·일관성도 확인한다.
5. 튜토리얼·방법 안내서의 명령은 안전한 범위에서 성공 경로와 대표 실패 경로를 실제로 실행한다. 실행할 수 없으면 이유와 미검증 범위를 명시한다.
6. 기본 번호 인용을 사용했으면 Python이 있을 때 scripts/validate-citations.py로 검사한다. 없으면 번호 재사용·최초 등장순·누락·중복·미사용 근거·링크 대상을 수동 확인하며 패키지를 자동 설치하지 않는다.
7. 실제 독자 테스트가 없으면 주목도·이해도·설득 효과를 검증했다고 단정하지 않는다. 선택한 독자와 작성 기준에 대한 적합성을 검토했다고 보고한다.
8. 작성·재구성에서는 변경과 검증 결과, 중요한 가정을 짧게 보고한다. 검토에서는 우선순위가 높은 문제부터 위치·독자 영향·수정 방향을 제시한다.

완료 여부는 문장의 유창함뿐 아니라 의도한 독자가 필요한 이해·판단·태도·행동의 변화를 얻도록 글이 구성됐는지로 판단한다.