문서 자동화
코드 변경으로 준비된 문서 수정안을 근거와 함께 검토하고 반영하는 흐름을 설명합니다.
코드가 바뀌면 수정안이 먼저 도착합니다. Specify는 푸시된 변경을 읽고 영향을 받는 문서를 찾아 검토할 수정안을 준비합니다. 반영은 팀이 정한 정책을 따릅니다.
수정안이 준비되는 과정
- 문서 프로젝트의 소스 브랜치에 코드가 반영됩니다. 해당 소스에 push 시 실행이 켜져 있어야 합니다.
- Specify가 변경 내용과 프로젝트가 관리하는 문서를 대조해 영향을 받는 문서를 찾습니다.
- 문서마다 변경 근거와 수정 전후를 담은 수정안을 준비합니다.
수정안에 담기는 것
| 항목 | 설명 |
|---|---|
| 변경 근거 | 어떤 코드 변경 때문에 이 문서를 고쳐야 하는지 |
| 수정 전후 | 문서의 어느 부분이 어떻게 바뀌는지 |
| 반영 범위 | 수정안이 영향을 주는 문서와 섹션 |
검토하고 반영하기
수정안의 근거와 수정 전후를 확인한 뒤 승인하면 문서에 반영됩니다. 사람이 검토하고 승인한 변경만 반영되는 것이 기본 흐름입니다.
새 프로젝트는 자동 반영 없이 시작합니다. 변경 내용과 근거를 확인할 수 있으며, 이후 반영 방식은 프로젝트 설정과 적용 정책에 따릅니다. 자동 반영이 허용된 경우에는 저위험 변경이 자동 승인될 수 있습니다.
좋은 검토를 위한 체크리스트
- 근거로 제시된 코드 변경이 실제로 문서 내용과 관련이 있는가
- 삭제되거나 이름이 바뀐 항목이 문서 전체에서 일관되게 반영되었는가
- 예시 코드, 요청·응답 예시가 새 동작과 일치하는가
- 사람이 판단해야 하는 설명(설계 의도, 운영 정책)이 자동 수정으로 덮이지 않았는가
프로젝트 상태
프로젝트 목록의 상태 배지로 검토가 필요한 프로젝트를 찾을 수 있습니다.
| 상태 | 의미 |
|---|---|
| 최신 | 관리 중인 문서가 소스와 맞춰져 있습니다. |
| 작성 중 | 문서 생성이나 수정 작업이 진행 중입니다. |
| 확인 필요 | 검토할 변경이나 확인이 필요한 작업이 있습니다. |