[개발자의 글쓰기] 4장. 독자 관점에서 릴리스 문서와 장애 보고서 쓰기

이 글은 "개발자의 글쓰기"를 읽고 좋은 구절들을 기록하거나 느낀 점을 기록하는 글입니다.

개발자의 글쓰기

4장은 릴리스 문서와 장애 보고서에 관한 이야기를 주로 다룬다.

 

프로젝트를 진행하며 문서화를 해본 적이 없어서 앞으로는 이렇게 해야겠다 라는 생각을 가진 것이 전부 인 것 같다. 

 

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

체인지 로그(changelog, 변경 기록)는 웹 사이트나 프로그램을 제작하는 것 같은 어떤 프로젝트를 진행할 때에 변경 사항에 대한 기록이다. 많은 오픈소스 프로젝트에서는 체인지 로그 파일을 가장 상위에 포함해서 배포한다.

 

보고서를 간단히 쓰면 한 일이 없어 보이고 자세히 쓰면 너무 길어 아무도 읽지 않아 무용지물이 되어 버린다.

뭐든 적당한 게 좋은 것 같다.

 

1. 선정하기
2. 분류하기
3. 요약하기
4. 종합하기

총 4단계를 거쳐서 진행하면 좋다

 

1. 선정하기

체인지 로그로 사용할 것과 안 할 것을 구분해야 한다.

작성하는 것은 개발자이지만 독자의 입장과는 다른 관점이기 때문이다.

 

2. 분류하기

비슷한 체인지 로그끼리 묶어야 한다.

두 가지 기준이 있다.

첫 번째 방법은 개발 관점에서 묶는다. 이 방법은 독자가 개발자인 경우 유용하다.

두 번째 방법은 사용자 관점에서 묶는다. 이 방법은 독자가 일반 사용자인 경우 유용하다.

 

3. 요약하기

문장 단위로 요약한다.

서술식 문장을 개조식 문장으로 바꾸는 것이다 ([개발자의 글쓰기] 1장에서 간단히 정리해두었음)

 

4. 종합하기

체인지 로그 첫 줄에 릴리스 내용 전체를 종합해서 한 문장으로 적어야 한다.

 

2. 릴리스 문서를 쓰는 순서

문제 -> 문제점 -> 해결책 -> 후속 계획 순으로 작성한다.

 

하나의 문제에 문제점은 여러 가지이며 모두 해결하기에 시간과 인력이 부족하기 때문에 선택해서 해결할 수밖에 없다.

어떤 문제점을 독자에게 정확히 알려주는 것이 릴리스 문서이다.

 

예)

(문제) 이미지 서비스에서 이미지의 크기가 기준보다 크면 홈페이지가 멈추는 문제가 있었습니다.

(문제점) 파악한 원인으로는 이미지 크기의 용량 초과, 잘못된 DB설계 등이었습니다.

(해결책) 업로드 시 이미지 크기를 제한함으로써 홈페이지가 멈추는 현상을 해결했습니다.

(후속 계획) 후속 조치로 DB 재설계를 검토하겠습니다.

 

또는

 

이미지 서비스에서 이미지 크기가 기준보다 크면 홈페이지가 멈추는 문제는
업로드 시 이미지 크기를 제한함으로써 해결했습니다.
추후 DB 재설계를 검토하겠습니다. 

 

이렇게 줄일 수도 있다.

 

3. 장애 보고서의 특징

1. 장애 보고서는 개발자가 원할 때 쓸 수 없다.

장애 발생 전에 미리 쓸 수도 없고, 장애를 예상하고 쓸 수도 없고, 오직 발생했을 때만 쓸 수 있다.

그래서 빠른 시간내에 작성을 해야 한다.

 

2. 장애의 1차 원인은 대부분 다른 원인의 결과다. 

장애의 원인의 원인의 원인을 찾다 더는 찾을 수 없을 때 그것이 최초 원인이다.

그 원인이 발생한 이유를 알아야 한다.

 

3. 장애 보고를 받는 윗사람은 대부분 개발자가 아니다.

그래서 비즈니스에 주는 영향으로 본다. 그들과 소통하기 위해 비즈니스 관점의 글쓰기가 필요하다.

 

4. 장애를 해결했다고 해서 100% 해결한 것은 아니다.

지금 장애를 해결했다고 다시는 재발하지 않는다는 보장은 없다.

보고 할 때는 확정적이고 신뢰할 만한 결단을 정치적으로 내려야 한다.