집필: 주제 쓰고 편집하기

쓰기 전에

스타일 규칙과 저장소 루트의 spec/conventions.md를 읽는다.
저장소 루트의 spec/structure.md를 확인해 주제가 어디에 들어맞고 어떤 번호여야 하는지 본다.

새 주제 쓰기

부와 그 부에서 다음으로 비어 있는 소수 번호를 고른다. 번호는 연속적이므로 새 주제는 보통 그 부의 마지막 주제 다음 번호를 가진다.
주제 템플릿에서 locales/en-gb-oxendict/topics/PP-CC-slug.md (0으로 채운 대시 구분 접두사, 예: 02-01-...)를 만든다. 옥스퍼드 철자로 쓰고(spec/oxford-spelling.md 참조), 나머지 세 로케일은 절대 직접 편집하지 않는다.
템플릿대로 쓴다. 내용 주제에는 모든 섹션이 필요하다. 개요, 핵심 원칙, 권고, 트레이드오프(표 포함), 토론 질문, 부문별 시각(스타트업, 소기업, 대기업, 정부), 예시(기업 하나와 정부 하나), 비즈니스 케이스, 안티패턴, 5단계 성숙도 모델, 토론 아이디어, 핵심 정리, 참고 문헌이다.
조작 경로를 밝힌다. 모든 메트릭 패밀리에는 “팀이 측정 대상을 개선하지 않고 이 숫자를 좋아 보이게 하려면 어떻게 하는가, 그리고 어떤 가드레일이 그것을 잡아내는가”에 대한 명시적인 답이 필요하다(주제 1.2 참조).
용어는 처음 쓸 때 정의한다. 핵심 개념에는 처음 언급할 때 Wikipedia 링크를 추가한다. 본문에서만.
관련 주제는 소수 번호로 교차 참조한다. 예: “(주제 2.1)“.
주제를 spec/structure.md에 추가한다.
부 소개(N.0)가 주제를 나열한다면 거기에 항목을 추가한다.
python3 tools/localize.py를 실행해 주제를 en-001, en-gb, en-us로 파생한다.
just nav를 실행하고, 이어서 just test를 실행한다.

기존 주제 편집하기

섹션 순서와 제목을 유지한다. 테스트는 내용 주제가 필요한 모든 섹션을 여전히 가졌는지 검사한다.
편집이 그것들을 대상으로 하지 않는 한 인라인 정의, Wikipedia 링크, 표, 참고 문헌 목록을 유지한다.
엠 대시나 금지된 문구를 들여오지 않는다. 문장을 고칠 때는 대시를 끼워 넣지 말고 다시 쓴다.
이후 python3 tools/localize.py를 실행해 편집된 en-gb-oxendict 원천에서 en-001, en-gb, en-us를 다시 파생한다.

이름 변경 또는 번호 재부여

locales/en-gb-oxendict/에서 파일 이름을 바꾸고, # N.M Title 제목을 갱신하고, spec/structure.md를 갱신하고, 옛 번호를 가리키는 모든 교차 참조를 갱신한다.
python3 tools/localize.py를 실행해 나머지 세 로케일의 파일 이름도 바꾼다(같은 상대 경로에서 네 개 모두를 파생한다).
just nav와 just test를 실행한다. 테스트는 H1과 파일 이름의 불일치, 번호의 빈틈, 원천에서 벗어난 로케일, 깨진 링크를 지적한다.

어조 알림

독자가 성공하기를 바라는 경험 많은 동료처럼 써라. 따뜻하고, 평이하고, 직접적이고, 쓸모 있게. 짧은 문장. 군더더기 없이.