4장. 독자 관점에서 릴리스 문서와 장애 보고서 쓰기
1. 체인지 로그를 분류, 요약, 종합하는 법#
체인지 로그의 양과 만족도의 관계#
- 일을 하고 상사나 고객에게 글로 보고해야 할 때가 있습니다. 이때 글을 줄이면 일을 안한 것처럼 보입니다.
- 반대로, 너무 많이 쓰면 이또한 좋지 않습니다.
- 적절한 양으로 쓰는 것이 중요합니다.
1단계: 선정하기#
- 체인지 로그 중에서 쓸 것과 없앨 것을 구분하는 것이 중요합니다.
| 개발자가 | |||
|---|---|---|---|
| 노력을 많이 들인것 | 노력을 덜 들인 것 | ||
| 독자가 | 관심 있는 것 | 1순위 | 2순위 |
| 관심 없는 것 | 3순위 | 4순위 |
- 관심에 따라, 체인지 로그 선정에 큰 영향을 끼칩니다.
- 회사의 순위까지 고려하면 다음과 같이 나타낼 수도 있습니다.
| 회사가 말하고 싶다 | 개발자가 말하고 싶다 | 독자가 듣고 싶다 | 순위 | 수준 | 예시 |
|---|---|---|---|---|---|
| O | O | O | 1순위 | 자세히 | 인공지능 추천 추가 |
| O | O | X | 2순위 | 간단히 | 대용량 네트워크 증설 |
| O | X | O | 3순위 | 간단히 | UI 개선 |
| O | X | X | 4순위 | 주석 | 면책 조항, 정책 변경 |
| X | O | O | 5순위 | 참조 | 작업 과정, 레퍼런스 |
| X | O | X | 삭제 | - | 성과가 낮은 오류 수정 |
| X | X | O | 삭제 | - | 경쟁력 없는 기능 추가 |
| X | X | X | 삭제 | - | 사소한 오류 수정 |
2단계: 분류하기#
- 비슷한 체인지 로그를 선정했으면 비스한 체인지 로그까지 묶어야 합니다.
- 첫번째 방법은 개발 관점에서 비슷한 작업을 묶는 방법입니다.
- 두 번째 방법은 독자가 일반 사용자인 경우에 유용하며, 사용자 관점에서 비슷한 것끼리 묶는 방법입니다.
3단계: 요약하기#
- 체인지 로그르 분류하면 문장 단위로 요약합니다.
- 요약 방법 중에서 서술식 문장을 개조식 문장으로 만들면 더 자연스럽습니다.
4단계: 종합하기#
- 위의 릴리스 내용 전체를 종합해서 한 문장으로 만들어서, 작성해야 합니다.
- 전체를 종합하는 방법은 분석과 반대입니다.
- 위를 종합하면 다음과 같은 형태로 만들 수 있습니다.
시간 절감, 다양한 닉네임, 정확한 사용, 결과를 쉽게 확인, 결과를 빠르게 확인, 편안한 마음으로 서비스 이용
- 이를 한 문장으로 만들려면, 핵심이 되는 것을 발췌해야하며 앞의 1순위 방법을 사용해야 합니다.
게임방에 더 빨리 입장하고 게임 결과를 바로 확인할 수 있도록 다음과 같이 변경
2. 고객에게 유용한 정보를 쓰자#
개발자 관점과 고객 관점#
- 체인지 로그는 개발자가 변경한 내용을 적은 것입니다.
- 외부 개발자나 일반 사용자가 보는 체인지 로그를 쓸 때는 개발자 관점이 아니라 고객 관점에서 써야합니다.
- 좋은 예시는 다음과 같습니다.
- 이러한 관점은 정해져있는 것은 아닙니다.
과거를 리뷰하고 미래를 보여주자#
- 체인지 로그에는 '한 일'을 적습니다.
- 다만, 고객이 요구하거나 불평한 것이 있다면 기약없이 기다림을 주지않기 위해 다음 릴리스 항목으로 검토하는 것이 있다면 중요한 것은 공개하는 것도 좋습니다.
Semantic Versioning(유의적 버전)#
- 체인지 로그는 버전 번호와 항상 같이 사용됩니다.
- 버전 1.2.2 -> 1.2.3 / 간단한 패치를 의미, 이전 버전과 호환를 의미합니다.
- 버전 1.2.2 -> 1.3.0 / 새로운 기능을 추가했을 때입니다.
- 버전 1.2.2 -> 2.0.0 / 전면적인 업데이트이며 이전 버전과 거의 호환되지 않는다고 볼 수 있습니다.
- 다만, 버전 번호를 올리는 단일 표준이 없습니다.
- 유의적 버전에 대한 상세 내용은 다음과 같습니다.
3. 릴리스 문서는 문제 해결 보고서처럼 쓰자#
문제와 문제점을 구별하자#
- 체인지 로그는 몇 줄로 간단히 쓸 때가 많습니다. 그러나 기업에서 하는 사업에 따라 고객에게 제공해야할 때도 있습니다.
- 버그를 잡거나 새로운 기능을 추가하거나 성능을 개선하는 것은 모두 어떤 문제를 해결하기 위해서입니다.
- 문제를 해결한다는 것은 목표에 다다르지 못하는 문제를 해결함을 의미하며 발생형, 탐색형, 설정형으로 구분됩니다.
- 발생형 문제는 당장 발생해 해결하기 위해 고민하는 문제입니다.
- 탐색형 문제는 현재 상황을 개선하거나 효율을 높이는 문제입니다.
- 설정형 문제는 미래 상황에 대응하는 문제입니다.
- 버그를 수정하는 것, 기능과 성능을 개선, 새로운 기능을 만드는 것 모두 문제를 해결하는 것입니다. 이때 문제와 문제점을 구별해야 합니다.
문제, 문제점, 해결책, 후속 계획 순으로 적자#
- 하나의 문제에 문제점은 여러 가지고, 여러 가지 문제점을 모두 해결하기에는 예산과 인력이 부족하므로 특정 문제점을 선택할 수 밖에 없습니다.
- 릴리스 문서는 결국 개발자가 문제점 하나를 선택해서 해결한 결과입니다.
법적인 문제를 고려해서 쓰자#
- 릴리 노트의 핵심은 문제 해결의 과정과 결과를 고객에게 알려주는 것입니다.
- 릴리스 노트를 통해 거래 개발자에게 어떤 행동을 유도할 때는 그 행동이 필수인지, 권장인지, 선택인지를 명확히 알려줘야 합니다.
필수#
~해야 한다,~하지 않으면 안된다,~하면 안된다,~해서는 안된다
권장#
~할 것을 권장한다,~하는 것이 좋다,~하는 것이 이상적이다
선택#
~할 수도 있다,~해도 된다,~하는 방법이 있다
4. 비즈니스를 이해하는 장애 보고서 쓰기#
장애 보고서의 특징#
- 첫째, 장애 보고서는 개발자가 원할 대 쓸 수 없습니다.
- 둘째, 장애의 1차 원인은 대부분 다른 원인의 결과다.
- 셋째, 장애 보고를 받는 윗사람은 대부분 개발자가 아니다.
- 넷째, 장애를 해결했다고 해서 100% 해결한 것은 아니다.
장애 보고서를 쓸 때는 다음의 글쓰기 방법이 필요합니다.
- 질문에 대답하는 신속한 글쓰기
- 원인과 이유를 찾는 분석적 글쓰기
- 상사를 고려하는 비즈니스 관점의 글쓰기
- 원하는 것을 얻는 정치적 글쓰기
질문에 대답하는 신속한 글쓰기#
사용자가(주어) 결제를(목적어) 할 수 없다(서술어)같은 식으로 단순하게 작성합니다.- 이를 일단 적고, 정리를 합니다.
원인과 이유를 찾는 분석적 글쓰기#
- 문제 해결 기법 중에 5Whys가 있으며 이는 어떤 원인을 찾을 대 근본적인 원인을 찾는 기법입니다.
- 문제의 원인이 되는 인과 관계를 탐색할 때 다섯 번 반복해서 원인이 무엇인지 질문하는 방식입니다.
- why는 어떤 일 또는 사람을 의미합니다.
- 대부분의 경우, IT분야에서 장애는 재발합니다.
- 많은 경우, 개발자 사이의 커뮤니케이션 오류가 바로 핵심 원인입니다.
상사를 고려하는 비즈니스 관점의 글쓰기#
- 장애 보고서를 비즈니스 관점으로 쓴다는 것은 매출과 비용 관점으로 설명한다는 것입니다.
- 개발자 관점은 결제 기능이 작동하지 않은 것이지만, 비즈니스 관점은 기대 매출의 손실이 발생한 것입니다.
- 즉, 장애로 인한 손실을 계산하는 것이 곧 비즈니스 관점으로 장애를 보고하는 방법입니다.
원하는 것을 얻는 정치적 글쓰기#
- 상사는 모호한 표현을 싫어합니다.
- 따라서, 이를 퍼센트로 정확하게 말하고 향후 예산 등을 받아내는 방법이 필요합니다.
| 장애 재발 가능성 | 표현 |
|---|---|
| 1% | 절대 재발하지 않는다 |
| 10% | 재발하지 않는다 |
| 20% | 재발할지도 모른다 |
| 30% | 재발할 수도 있다 |
| 40% | 재발한다고 볼 수도 있다 |
| 50% | 재발할 수 있다 |
| 60% | 재발하지 않는다고 볼 수 없다 |
| 70% | 재발한다고 보여진다 |
| 80% | 재발한다 |
| 90% | 재발할 것이 틀림없다 |
| 99% | 반드시 재발한다 |
- 정확한 단어와 문장으로 현상과 사실얼 있는 그대로 표현해야 합니다.