4장 ) 릴리스문서와 장애보고서 쓰기

1. 체인지 로그를 분류, 요약, 종합하는 법

상사나 고객의 만족도는 체인지 로그의 양이 적절할 때 가장 높다.

체인지 로그를 적절한 양으로 쓰기 위해서는 일정한 기준으로 선정하고 비슷한 것끼리 분류한 뒤 문장을 요약해야 한다.

• 1단계 : 선정하기
• 2단계 : 분류하기
• 3단계 : 요약하기
• 4단계 : 종합하기

1단계: 선정하기

• 체인지 로그의 양을 줄이기 위해서는 쓸것과 없앨것을 구분하는 기준이 필요하다.
• 개발자가 노력을 많이 들인 것 / 회사가 말하고 싶은 것 / 독자가 듣고 싶은 것
• 우선순위대로 작성한다.

2단계: 분류하기

• 공개할 체인지 로그를 선정 후 비슷한 체인지 로그끼리 묶어야한다.
  • 개발 관점에서 비슷한 작업을 묶는 방법. (독자가 개발자인 경우)
    • 새로운 기능 추가, 기능 개선, 오류 수정
  • 사용자 관점에서 비슷한 것끼리 묶는 방법.(독자가 일반 사용자인 경우)

3단계: 요약하기

• 체인지 로그 분류 후에는 문장 단위로 요약한다.
• 서술식 문장을 개조식 문장으로 바꿔 내용을 축약하고 의미를 분명히 한다.
  • 불필요한 부사, 횽영사, 조사, 어미를 없애고 정확하고 적절한 단어로 대체.

4단계: 종합하기

• 릴리스 내용 전체를 종합해서 한 문장으로 만들고, 그것을 체인지 로그 첫 줄에 적는다.
• "엘리베이터 스피치"
• 여러 체인지 로그를 특정 개념의 하위 요소로 넣는다.
• 특성과 결과를 합쳐서 서술

2. 고객에게 유용한 정보를 쓰자

개발자 관점과 고객 관점

체인지로그는 개발자가 변경한 내용을 적은 것이다.

• 고객 관점으로 쓰려면 변경사항이 고객에게 끼치는 영향을 체인지 로그에 추가해서 기술한다.
  • ex) 개발자의 문제 : 화면이 멈춤 / 고객의 문제 : 애니메이션 스티커를 댓글에 사용할 수 없음.
• 고객이 얻는 헤택이 무엇인지 분명히 얘기해줘야한다.
• 고객의 문제 해결 + 해결책을 제시
• 체인지 로그는 하나의 관점으로만 쓸 필요는 없다. 내용에 따라 관점을 적절히 선택하는 것이 중요하다.
• 다음 릴리스 항목으로 검토하는 것이 있다면 중요한 것은 공개하는 것이 좋다.

Semantic Versioning (유의적 버전)

• 체인지 로그는 무엇인가 바뀌었을 때 스므로, 버전 번호와 항상 같이 사용된다.
• 버전을 올리는 가이드로 Semantic Versioning 사용하면 좋다.
  • https://semver.org/lang/ko/ 참고

3. 릴리스 문서는 문제 해결 보고서처럼 쓰자

• 발생형 문제 : 눈 앞에 발생해 당장 걱정하고 해결하기 위해 고민하는 문제
  • ex) 프로그램 에러
• 탐색형 문제 : 현재 상황을 개선하거나 효율을 높이는 문제
  • ex) 프로그램 개선, 시스템 효율화
• 설정형 문제 : 미래 상황에 대응하는 문제
  • ex) 새로운 기능, 대폭적인 업그레이드

문제, 문제점, 해결책, 후속 계획 순으로 적자

릴리스 문서는 결국 개발자가 문제점 하나를 선택해서 해결한 결과이다.

→ 따라서 어떤 문제점을 선택했는지를 독자에게 정확히 알려줘야 한다.

• 릴리스 노트를 통해 거래 회사 개발자에게 어떤 행동을 유도할 때는 그 행동이 필수인지, 권장인지, 선택인지를 명확히 알려줘야 한다. → 면책

4. 비즈니스를 이해하는 장애 보고서 쓰기

장애 보고서의 특성

1. 장애 보고서는 개발자가 원할 때 쓸 수 없다.
   → 장애가 발생해서 인지하는 순간부터 장애 해결 직후 또는 다음날 오전. 따라서 신속한 글쓰기가 필요하다.
2. 장애의 1차 원인은 대부분 다른 원인의 결과다.
   → 분석적 글쓰기 필요
3. 장애 보고를 받는 윗사람은 대부분 개발자가 아니다.
   → 비즈니스 관점의 글쓰기가 필요
4. 장애를 해결했다고 해서 100% 해결한 것은 아니다.
   → 정치적 글쓰기 필요

원인과 이유를 찾는 분석적 글쓰기

문제 해결 기법 5Whys

: 문제의 원인을 찾을 때 피상적인 원인이 아니라 근본적인 원인을 찾는 기법.

• why의 뜻을 두가지로 이해해야한다.
  • 사물이나 현상, 동작이 문제를 초래하는 원인
  • 사람이 문제를 초래한 이유

IT 분야에서 장애는 대부분 재발한다. 대부분은 사람의 문제이다.

장애의 원인과 이유를 파악 후 해결해야한다.

개발자 사이의 커뮤니케이션 오류를 해결하기 위해 어떠한 변경이 있을 때 그 내용을 공유하는 주간 변경 회의를 하거나 변경 관련 이메일을 보낼 때 모두 참조하게 하는 것도 하나의 방법이다.

상사를 고려하는 비즈니스 관점의 글쓰기

• 비즈니스에서 모든 활동은 매출과 비용으로 연결되고 측정된다.
• 따라서 장애로 인한 손실을 계산하는 것이 곧 비즈니스 관점으로 장애를 보고하는 방법이다.

1. 장애 발생 시간대의 기대 매출을 계산
2. 장애 때 실제 발생한 매출을 계산.
3. 매출 손실은 기대 매출에서 실제 매출을 뺀 값이다.
4. 장애 직후 특정 시간까지 매출이 과거 평균보다 월등히 높아진다면 이때 늘어난 매출은 장애로 인해 지연된 매출이다. 개발자 입장에서는 지연 매출도 결국은 매출임을 주장해야 한다.
5. 지연매출도 매출로 인정된다면 매출 손실은 기대 매출에서 실제 매출과 지연 매출을 뺀 값이 된다.

정치적 글쓰기를 통한 정확한 단어와 문장으로 현상과 사실을 있는 그대로 표현해야한다.

---

느낀점

비즈니스 관점에서 개발 및 보고서를 쓸 때의 방법에 대해 배우게 되어 좋았다. 개인적으로 지금까지는 항상 오류가 있어도 어찌저찌 해결하고 나면 원인이 뭔지 이런것 위주로 보기보다는 해결했다는 것 자체에 중점을 두고, 팀원들에게는 해결했다고만 말하는 방식으로 진행해왔는데 실무에서 그런건 말도 안되는 것 같다.

일단은 장애 보고서 등을 써야하기 때문에 원인과 해결법 그리고 앞으로 대책 등을 파악해서 정리하는 연습부터 해야겠다.