짧은 기준을 먼저 제시한다. 선택이 혼동되는 곳에는 피할 예시와 권장 예시를 코드, SQL 또는 테스트로 보여준다. 실제 구현과 테스트가 있으면 해당 경로를 연결한다.
예시 아래에는 결과가 달라지는 이유와 그대로 적용하면 안 되는 조건만 설명한다. 긴 배경 설명보다 판단에 필요한 작은 예시를 사용한다.
업무 정책서는 구현 코드보다 조건과 결과가 드러나는 사례를 사용한다. 세부 형식은 정책 작성 가이드를 따른다.
- 독자가 판단하거나 작업하는 데 필요한 내용만 작성한다.
- 문서의 역할을 되풀이하는 안내, 당연한 주의사항과 반복적인 면책 문구를 넣지 않는다.
- 가상 예시는 실제 구현처럼 소개하지 않는다. 예시 제목과 문맥으로 구분한다.
- 조건과 결과가 분명한 완결된 문장으로 작성한다.
- 구현 경로와 명령은 현재 저장소에서 확인할 수 있는 것만 연결한다.
설계 원칙, 개발 절차, 업무 정책과 운영 규칙은 각각 한곳에서 관리한다. 같은 원칙을 여러 문서에 복제하지 않고 해당 문서를 링크한다.
문서와 구현이 다르면 현재 동작을 정답으로 간주하지 않는다. 차이를 확인하고 확정된 결정에 맞춰 관련 문서와 구현을 함께 갱신한다.
미결정 정책은 기존 코드나 관례로 확정하지 않는다. 선택지와 결과를 정리해 논의하고, 확정 후 반영한다.