개발자의 글쓰기 4장
🖋 4장 : 독자 관점에서 릴리스 문서와 장애 보고서 쓰기
📎 체인지 로그를 분류, 요약, 종합하는 법
- 체인지 로그는 읽기 좋게 적절한 양으로 써야 만족도가 뫂다.
- 체인지 로그를 적절한 양으로 쓰려면 일단은 체인지 로그를 최대한 많이 쓰고 일정한 기준으로 선정하고 비슷한 것끼리 분류한 뒤 문장을 요약해야한다.
- 1단계 : 선정하기
- 2단계 : 분류하기
- 3단계 : 요약하기
- 4단계 : 종합하기
1단계: 선정하기
- 체인지 로그의 양을 줄이려면 체인지 로그 중에서 쓸 것과 없앨 것을 구분하는 기준이 필요하다.
- 회사, 개발자, 독자(고객)의 관심으로 분류해서 체인지 로그를 선정하고 순위나 수준을 결정해야 한다.
2단계 : 분류하기
- 공개할 체인지 로그를 선정했으면 비슷한 체인지 로그끼리 묶어야 한다 .
- 개발 관점에서 비슷한 작업을 묶기 (새로운 기능 추가/ 기능 개선/ 오류 수정)
- 사용자 관점에서 비슷한 것끼리 묶기 (준비/ 실행 중/ 종료)
- 여러 체인지 로그를 특정 개념의 하위 요소로 넣는 것
3단계 : 요약하기
- 체인지 로그를 분류했으면 문장 단위로 요약
- 서술식 문장을 개조식 문장으로 바꾸는 방법을 쓰면 내용이 자연스럽게 축약되고 의미는 더 분명해진다.
- 불필요한 부사나 형용사, 조사나 어미를 없애고, 정확하고 적절한 단어로 대체
4단계 : 종합하기
- 이번과 비교해서 뭐가 다르고 핵심과 컨셉이 무엇인지 한마디로 알려줘야 함
- 릴리스 내용 전체를 종합해서 한 문장으로 만들고 그것을 체인지 로그 첫 줄에 적어야 함
- 종합은 분석과 반대여서 특성과 결과를 합쳐서 서술하는 것
📎 고객에게 유용한 정보를 쓰자
- 체인지 로그는 개발자가 변경한 내용을 적은 것이다.
- 외부 개발자나 일반 사용자가 보는 체인지 로그를 쓸 때는 개발자 관점이 아니라 고객 관점에서 써야 한다.
- 고객 관점으로 쓰려면 변경사항이 고객에게 끼치는 영향을 체인지 로그에 추가해서 기술하면 된다.
- 내용에 따라 관점을 적절히 선택하는 것이 중요하다.
- 다음 릴리스 항목으로 검토하는 것이 있다면 중요한 것은 공개하는 게 좋다. 이전에 릴리스하면서 잡은 버그가 완벽히 해결됐는지, 새 기능은 어떤 것을 많이 사용하는지도 얘기하자.
Semantic Versioning(유의적 버전)
- 세 번째 자리에서 버전을 올림: 간단한 패치. 이전 버전과 호환
- 두 번째 자리에서 버전을 올림: 새로운 기능 추가. 이전 버전에서는 새로운 기능 사용 불가
- 첫 번째 자리에서 버전을 올림: 전면적인 업그레이드. 이전 버전과 호환이 거의 불가
- 깃허브 Semantic versioning
📎 릴리스 문서는 문제 해결 보고서처럼 쓰자
- 릴리스 노트는 문제, 문제점, 해결책, 후속 계획 순서로 쓰는 것이 좋다.
- 릴리스 노트의 핵심은 문제 해결의 과정과 결과를 고객에게 알려주는 것.
📎 비즈니스를 이해하는 장애 보고서 쓰기
- 장애 보고서는 개발자가 원할 때 쓸 수 없다.
- 장애의 1차 원인은 대부분 다른 원인의 결과
- 장애의 원인을 정확히 알아내려면 원인의 원인을 계속 찾아 나가야 한다.
- 장애 보고를 받는 윗사람은 대부분 개발자가 아니다.
- 장애를 해결했다고 해서 100% 해결한 것은 아니다.
5Whys
- 어떤 문제의 원인을 찾을 때 피상적인 원인이 아니라 근본적인 원인을 찾는 기법. 문제의 원인이 되는 인과 관계를 참색할 때 다섯 번 반복해서 원인이 무엇인지 질문하는 방식