📝 김철수님의 '개발자의 글쓰기'를 읽고 정리한 글입니다. 문제가 될 경우 삭제 조치하도록 하겠습니다.

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

1.1 체인지 로그의 양과 만족도의 관계

업무를 하고 나서 업무의 내용을 글로 보고해야 할 때 글을 너무 간단히 쓰면 한 일이 없어 보이고 자세히 쓰면 아무도 읽지 않는데 이를 체인지 로그라고 한다. 물론 이후에 독자와의 소통할 내용이기도 하다.

그렇다면 동료, 상사, 독자를 만족시키기 위해서는 체인지 로그를 어떻게 써야 할까?

체인지 로그의 양을 적절하게 쓰기

체인지 로그를 적절한 양으로 쓰려면 일단 최대한 많이 써야 한다. 그다음 아래의 4단계를 수행하면 된다.

1단계 : 선정하기

체인지 로그의 양을 줄이려면 선택과 집중이 필요하다.

개발자는 자기가 오랜 시간 노력한 결과물을 쓰고 그렇지 않은 것은 빼는 경향이 있는데 이는 잘못되었다.

개발자에게는 별거 아니었지만 독자에게는 중요한 것이 있을 수 있기 때문이다.

개발자의 노력과 독자의 관심을 기준으로 순위를 짜면 더 전략적으로 선정할 수 있을 것이다.

1순위 : 개발자가 노력을 많이 들인 것 && 독자가 관심 있는 것
2순위 : 개발자가 노력을 덜 들인 것 && 독자가 관심 있는 것
….

더 나아가 회사 입장, 디자인팀, 마케팅팀, 운영팀의 입장도 있다. 결국 체인지 로그는 회사의 공식 발표이며 독자와 직접 소통하는 문건이기에 개발자 입장에서만 체인지 로그를 쓰면 안 되는 것을 주의하자.

여러 가지의 경우의 수를 통해 표를 만들어 순위를 정해 체인지 로그를 작성해서 선정하면 된다.

회사가 말하고 싶다	개발자가 말하고 싶다	독자가 듣고 싶다	순위	수준	예시
O	O	O	1	자세히	인공지능 추천 추가

2단계 : 분류하기

비슷한 체인지 로그끼리 묶어야 한다. 이때 두 가지 방법이 있다.

첫 번째 방법은 개발 관점에서 비슷한 작업을 묶는 방법으로 독자가 개발자인 경우에 유용하다.

즉 릴리스 문서에 사용하는 새로운 기능 추가, 기능 개선, 오류 수정으로 묶을 수 있다.

1. 새로운 기능 추가

• 닉네임을 만들 때 특수 문자를 입력하는 기능을 추가했습니다.

2. 기능 개선

• 게임 종료 후 바로 순위를 볼 수 있도록 개선했습니다.

3. 오류 수정

• 애니메이션 스티커가 갑자기 멈추는 오류를 수정했습니다.

두 번째 방법은 독자가 일반 사용자인 경우이다. 사용자 관점의 분류인 것이다. 예를 들어 사용자가 게임을 준비하고, 게임을 하고 종료하는 단계에 따라서 묶을 수 있다.

1. 게임 준비

• 닉네임을 만들 때 특수 문자를 추가하는 기능을 추가했습니다.

2. 게임 중

• 애니메이션 스티커가 갑자기 멈추는 오류를 수정했습니다.

3. 게임 종료

• 게임 종료 후 바로 순위를 볼 수 있도록 개선했습니다.

3단계 : 요약하기

체인지 로그를 분석했으면 서술식 문장을 개조식 문장으로 바꾸면 자연스레 축약되고 의미는 더 분명해진다.

게임 준비

• 닉네임을 만들 때 특수 문자를 추가하는 기능을 추가했습니다.

개조식 문장으로 바꾸는 방법은 불필요한 부사, 형용사, 조사나 어미를 없애면 된다.

4단계 : 종합하기

종합하기 전에 엘리베이터 스피치를 생각하자 엘리베이터 스피치란 엘리베이터가 이동하는 그 짧은 시간에 사업 계획을 핵심만 종합해 말하는 방식이다.

• 그래서, 한마디로 뭘 한다는 거죠?
• 그래서, 핵심이 뭔가요?

체인지 로그도 상사나 고객이 보기 때문에 마찬가지이다. 이 점을 유의하면 될 것이다.

결론으로 들어가서 종합은 서술하는 것이다.

토끼는 동물이다처럼 개념화하지 않고 토끼는 귀가 밝다 처럼 특성으로 서술하거나 토끼는 잘 도망간다처럼 결과를 서술하는 것이다.

물론 특성과 결과를 합쳐도 된다. 토끼는 귀가 밝아서 잘 도망간다

1. 게임 준비

• 닉네임을 만들 때 특수 문자 추가 기능 추가 → 다양한 닉네임 설정 가능 → 자기를 더 잘 표현

2. 게임 중

• 애니메이션 스티커가 멈추는 오류 수정 → 정확한 사용

3. 게임 종료

• 게임 종료 후 바로 순위를 볼 수 있도록 개선 → 게임 결과를 더 빠르게 확인

여기서 다양한 닉네임, 정확한 사용, 결과를 빠르게 확인과 같은 특성과 결과를 정리해 한 문장으로 만들면 된다.

이 3가지 혹은 그 이상을 포괄하는 문장을 만들기는 어렵다. 그래서 핵심이 되는 것을 발췌해야 한다. 여기서 핵심이란 1단계에서 선정한 순위를 참고해 작성하면 된다.

게임방 입장 시간 절감과 게임 결과 바로 확인이 1순위라면 다음과 같이 정리할 수 있다.

게임방에 더 빨리 입장하고 게임 결과를 바로 확인할 수 있도록 다음과 같이 변경했습니다.

다시 개조식으로 바꿔보자

게임방에 더 빨리 입장하고 게임 결과를 바로 확인할 수 있게 변경

내용이 두 가지 이상이면 줄을 나누자

• 게임방에 더 빨리 입장
• 게임 결과 바로 확인

여기서 두 내용을 분석해 사용성, 안정성 편리성, 효율성 같은 추상적인 상위 개념을 만들어 넣자.

사용자 편리성 개선

• 게임방에 더 빨리 입장
• 게임 결과 바로 확인

4단계 까지 잘 수행했다면 체인지 로그가 완성된다.

사용자 편리성 개선

• 게임방에 더 빨리 입장
• 게임 결과 바로 확인

[세부 내용]
1. 게임 준비

• 닉네임 만들 때 특수 문자 입력 기능 추가

2. 게임 중

• 애니메이션 스티커가 멈추는 오류 수정

3. 게임 종료

• 게임 종료 후 바로 순위를 볼 수 있도록 개선

이제 체인지 로그를 종합했으므로 엘리베이터 스피치에도 대응할 수 있다.

• 그래서, 한마디로 뭘 한다는 거죠?

• 사용자가 서비스를 더 편리하게 쓸 수 있게 했습니다.

• 그래서, 핵심이 뭔가요?

• 사용자가 게임방에 더 빨리 입장하고 게임 결과를 바로 확인할 수 있습니다.

항상 체인지 로그를 개발자 관점에서 키워드만 나열했었고 작성하기 어려웠는데 이번에 좋은 방법을 알게 되어 다행이다.

무엇보다 체인지 로그는 개발자로서 거의 매일 쓰기 때문에 이 방법을 항상 실천해 봐야 겠다. 또한 고객 관점에서 혹은 여러 직종의 팀원 입장에서도 생각할 수 있게 되어 마인드도 확장된 느낌이다.

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

2.1 개발자 관점과 고객 관점

체인지 로그를 사내 개발자끼리만 본다면 한 일만 담백하게 적어도 상관없다. 하지만 외부 개발자 혹은 일반 사용자가 보는 체인지 로그를 쓸 때는 고객 관점에서 써야 한다.

고객 관점으로 쓰려면 변경사항이 고객에게 끼치는 영향을 체인지 로그에 추가하면 된다.

개발자 체인지 로그 :
댓글에서 애니메이션 스티커 때문에 화면이 멈추는 문제를 해결했습니다.

이것을 고객 관점에서 고객의 불편한 점을 알아야 한다.

• 개발자의 문제 : 화면이 멈춘 것
• 고객의 문제 : 애니메이션 스티커를 댓글에 사용할 수 없는 것

개발자가 문제를 해결했다면 당연히 고객의 문제도 해결된다.

• 개발자의 문제 해결 : 화면이 멈추지 않게 했다.
• 고객의 문제 해결 : 애니메이션 스티커를 댓글에 사용할 수 있다.

최종적으로 고객의 문제 해결을 앞쪽으로 옮기고, 개발자의 문제는 짧게 줄이며 개조식으로 바꾸면 다음과 같다.

애니메이션 스티커를 댓글에 정상 사용 가능(화면 멈춤 문제 해결)

UI 개선도 분명하게 사용자 관점에서 써줘야 한다.

• 개발자 관점 : 확인/취소 버튼 및 서로이웃 맺기 UI를 개선했습니다.
• 사용자 관점 : 확인/취소 버튼이 커져서 찾기가 더 쉬워졌습니다.

실제 사례를 보면 사용자 관점에서만 체인지 로그를 작성하지 않는 경우도 있다. 멜론을 보면 사용자 관점에서 쓴 것도 많지만 기타 소소한 서비스 개선과 오류가 수정되었습니다. 라는 개발자 관점의 체인지 로그들도 볼 수 있을 것이다.

사용자가 보기에 그다지 중요한 게 아니라면 개발자 관점으로 써도 된다.

네이버 밴드의 체인지 로그를 보면 채팅 답장 기능이 추가되었어요! 상대방 메시지를 꾹 눌러 답장쓰기를 해보세요. 라는 기능을 쓰도록 하는데 이 형식도 좋다.

2.2 과거를 리뷰하고 미래를 보여주자

체인지 로그에는 한 일을 적는다. 체인지 로그 자체가 개발의 결과니까 당연하긴 하다. 하지만 개발자에게는 해결해야 할 버그와 개발할 새 기능도 많다.

고객 입장에서도 요구한 거나 불평한 것이 이번 릴리스에 반영되지 않으면 무시당했다고 생각하거나 다음 릴리스를 기다릴 수밖에 없다. 즉 소통이 되지 않는 것이다.

검토 중인 항목이나 개발 중인 항목을 릴리스 노트에 보여주는 것도 좋다.

2.3 Semintic Versioning(유의적 버전)

체인지 로그는 버전 번호와 같이 사용된다. 버전 1.2.2 -> 1.2.3 이 꼭 들어간다.

하지만 업데이트 시 버전의 소수점 어디를 올려야 하는지 표준이 없다.

책에서는 깃허브 창업자인 톰 프레스턴 베르너가 정한 Semintic Versioning를 소개한다. 김대현 님이 번역한 글을 참고하자

간단히 정리하자면 X,Y,Z로 구분된다. 상위 버전이 올라가면 하위 버전은 0으로 초기화된다.

• X가 0인 것은 초기 내부 개발에서만 사용하고 최초 프로덕션 공개는 1.0.0이어야 한다.
• X는 기존 버전과 호환되지 않는 변화가 있을 때만 1씩 올린다.
• Y는 기존 버전과 호환되는 새로운 기능이 추가됐을 때 1씩 올린다.
• Y는 큰 규모의 패치가 있을 때 작은 규모와 구분하기 Z대신에 위해 올려도 된다.
• Z는 기존 버전과 완전 호환되면서 작은 규모의 패치가 있을 때 1씩 올린다.

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

3.1 문제와 문제점을 구별하자

체인지 로그는 몇 줄로 간단히 쓸 때가 많은데 기업에 소프트웨어를 판매하거나 SI 사업을 할 때 릴리스 문서를 정식으로 만들어 제공해야 한다. 이때는 단순히 정보 제공을 넘어 문제 해결 보고서라고 볼 수 있다.

체인지 로그는 문제 해결에 집중적이어서 문제와 문제점을 구별해야 한다. 그러면 문제점을 확실히 알 수 있어 문제 해결 보고서처럼 쓰기 용이해진다.

• 문제의 예 : 직원이 생산성이 떨어진다.
• 문제점의 예 : 술을 많이 마신다, 간이 상해서, 비타민 부족, 피로

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

하나의 문제에 문제점은 여러 가지인데 이를 다 해결하기에는 예산과 인력이 늘 부족하므로 특정 문제점을 선택할 수밖에 없다.

그러므로 어떤 문제점을 선택하느냐에 따라 문제 해결 방법은 완전히 달라진다.

그렇기에 개발자가 문제점 하나를 선택해서 해결한 결과가 릴리스 문서인데 이를 독자에게 정확히 알려줘야 한다.

아래의 문제, 문제점, 해결책, 후속 계획이 포함되어야 좋다.

• 문제 : 사용자가 급증하면 서버가 정지
• 문제점 : 잘못된 시스템 설정, 프로그램 비 최적화, 잘못된 DB 설계
• 해결책 : 시스템 설정 변경
• 후속 계획 : 프로그램 최적화, DB 재설계

3.3 법적인 문제를 고려해서 쓰자

릴리스 노트의 포함되어야 할 예시

• 문서 정보 : 제품명, 릴리스 이름, 릴리스 버전, 릴리스 날짜 등
• 개요 : 릴리스 노트의 주요 내용을 종합한 글
• 새로운 기능 : 이번 릴리스에 새롭게 추가한 기능
• 개선 사항 : 기존 기능을 향상하거나 안정성 등을 강화한 내용
• 버그 수정 : 버그 내용과 수정 사항
• 영향과 주의사항 : 릴리스로 인한 영향과 개발자의 주의사항
• 연락처 : 문의나 의견 접수를 위한 담당자 이름과 연락처 정보
• 면책 : 변경 사항인 릴리스 문서로 인한 법적 문제 발생 시 책임의 한계에 관한 내용

여기서 주의하게 볼 건 면책 사항이다. 릴리스 노트는 고객에게 보고하는 문서인 만큼 계약에 의한 산출물로 취급되는데 이는 법적 책임을 줄일 수 있는 내용인 면책 조항을 적는 게 좋다

면책에는 설치 권장, 업데이트 필수, 백업 선택 과 같은 내용이 들어 있는데, 이 세 가지는 명확히 알려줘야 한다.

필수

독자가 반드시 해야 할 일을 필수로 명시하면 독자가 그 일을 하지 않아서 생기는 문제에 책임을 지지 않는다.

• ~해야 한다.
• ~하지 않으면 안 된다.
• ~하면 안 된다.
• ~해서는 안 된다.

권장

어떤 문제를 해결하는 방법이 여러 가지 있는 경우 개발자가 우선순위를 정해줄 때 쓴다.

개발자가 권장하지 않은 방법을 써서 생기는 문제에는 책임을 지지 않는다.

• ~할 것을 권장한다.
• ~하는 것이 좋다.
• ~하는 것이 이상적이다.

선택

개발자가 독자에게 여러 옵션을 자유롭게 줄 수 있을 때 쓴다.

문제가 되지 않을 내용이거나 새로운 기능의 사용을 독촉할 때 쓴다.

• ~할 수도 있다.
• ~해도 된다.
• ~하는 방법이 있다.

이 세 가지 이외에도 혹시 모를 문제에 대비해야 한다. 즉 예외사항을 명시하는 게 좋다.

이 비디오 전송은 5배 이상의 속도를 낼 수 있습니다. 그러나 가상 데스크톱 환경의 구조적 제한으로 인해 비디오 전송이 원활하게 작동하지 않을 수 있습니다.

이러한 면책들을 회피로만 받아들이지 말고 다음 릴리스 노트에서 해결해서 적으면 좋다.

지난번 릴리스 노트에서 가상 데스크톱 환경의 구조적 제한으로 인해 비디오 전송이 원활하게 작동하지 않는 경우를 해결했습니다.

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

4.1 장애 보고서의 특징

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

장애가 발생하기 전 미리 예상하고 쓸 수 없기에 원할 때 쓸 수 없다.

장애를 인지하는 순간부터 해결 직후나 다음날 오전까지가 장애 보고서를 쓰는 시간이기에 장애를 해결하면서 동시에 신속하게 보고서를 써야 한다.

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

장애의 재발을 막기 위해선 원인만 해결하면 안 된다. 그 원인이 발생한 이유를 찾아야 한다.

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

대부분 개발자가 아니기에 비즈니스 관점의 글쓰기가 필요하다.

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

장애란 원래 예상하지 못한 데서 발생한 것이니 당장 급하게 해결했다고 해서 재발하지 않는다고 확정할 수 없다. 그런데 윗사람에게 보고할 때는 확정적이고 신뢰할 만한 결단을 정치적으로 내려야 한다.

그래서 정치적 글쓰기가 필요하다.

4.2 질문에 대답하는 신속한 글쓰기

글은 쓰는데 생각이 필요한 반면 대화는 글 쓰는 것처럼 한참 생각을 하면서 뜸을 들이지는 않는다. 그렇기에 먼저 대화를 글을 옮기는 게 좋다.

대화를 그대로 글로 옮김 → 개조식으로 정리 → 장애 항목 분리 → 보고서 작성

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

5Whys라는 문제 해결 기법이 있다. 이는 근본적인 문제 원인을 찾는 기법이다.

5개의 Why를 항상 숙지하고 개발자들 간 소통의 원활해야 한다. 그러면 장애가 재발하는 상황을 많이 줄여줄 것이다.

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

결제 시스템에 장애가 난다고 보자. 개발자 관점에서는 결제 기능이 작동하지 않은 것이지만, 비즈니스 관점은 기대 매출의 손실이 발생한 것이다. 그렇기에 장애로 인한 손실을 계산하는 게 곧 비즈니스 관점으로 장애를 보고하는 방법이다.

• 네트워크 장애로 24시간 동안 홈페이지 접속이 안 됐음
• 홈페이지 접속 장애로 네티즌 100명가량이 접속할 수 없었음
• 그로 인해 기대 매출 손실 100만원, 비용손실 10만원으로 총 100만원의 손실 발생

4.5 원하는 것을 얻는 정치적 글쓰기

장애는 보통 예상치 못한 데서 발생하기에 해결했다고 해서 재발할 가능성이 있다. 하지만 처음에 발생한 장애와 이후에 발생한 장애가 비슷해서 그 차이를 설명하기 어렵고 예매할 때가 있는데 윗사람은 확정적인 대답을 원한다.

확실하게 재발 가능성을 %로 보여주자.

161p 표 참고

그리고 쓰는 방식에도 차이가 있다.

• 냉방기 미교체시 화재 발생 엄려

이 글을 아래와 같이 바꿔 쓴다면

• 냉방기 폭발 시 서비스 전면 중단

윗사람이 놀라서 바로 냉방기를 교체할 것이다.
위의 예는 좀 극단적이지만 이러한 형식으로 작성하면 크게 봐서 회사에게 도움이 될 수도 있다.

하지만 허위보고와 얼버무리듯 보고하는 것은 안 된다. 정확한 단어와 문장으로 형상과 사실을 있는 그대로 표현해야 한다.

5. 4장을 읽고 느낀 점

• 체인지 로그는 독자에 따라 개발자 관점, 사용자 관점이 나누어지기에 체인지 로그 특성에 따라 맞는 방식으로 작성해야겠다.
• 1.1의 체인지 로그 작성 4단계를 활용하자.
• 사용자 관점에서 체인지 로그를 작성할 때는 해당 기능을 사용해 보라는 문구도 넣어주면 좋을 거 같다.
• 사용자 관점의 체인지 로그에서 검토 중인 항목과 개발 중인 항목을 체인지 로그에 넣으면 사용자들과 더 소통할 수 있다고 생각했다.
• 면책 사항을 회피 용도로 만 쓰기보다는 개선할 점이라고 생각해 다음 릴리스에 반영해 사용자에게 알리자.
• 장애보고서나 인터뷰를 할 때 신속하게 글을 쓰기 위해선 대화 형식으로 글을 옮긴 뒤 개요식으로 바꾼다.
• 5Whys로 문제를 해결하면 추후의 장애도 대비가 가능하다.
• 장애보고서는 기대 매출을 표기해 비즈니스 관점으로 작성하자.
• 장애보고서에는 %로 재발 가능성을 표기해 명확히 하자.