개발자의 글쓰기 - 릴리스 노트, 장애 보고서

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

---

개발자 관점과 고객 관점

 체인지 로그는 개발자가 변경한 내용을 적은 것이다. 하지만 체인지 로그를 보는 독자는 뭔가 새로운 것, 바뀐 것, 그래서 자기에게 좋거나 유익하거나 어떤 행동을 해야 할지 명확하게 지시하는 것을 보고 싶어 한다. 체인지 로그를 사내 개발자끼리만 본다면 한 일만 담백하게 적어도 상관없다. 하지만 외부 개발자나 일반 사용자가 보는 체인지 로그를 쓸 때는 개발자 관점이 아니라 고객 관점에서 써야 한다.

 고객 관점으로 쓰려면 변경사항이 고객에게 끼치는 영향을 체인지 로그에 추가해서 기술하면 된다. 예를 들어 다음과 같이 개발자가 문제를 해결한 내용만 기술한 체인지 로그가 있다고 하자.

댓글에서 애니메이션 스티커 때문에 화면이 멈추는 문제를 해결했습니다.

 이것을 고객 관점에서 살펴보자. 우선 고객의 불편이 뭔지 알아야 한다. 댓글에서 애니메이션 스티커 때문에 화면이 멈추는 것은 고객의 불편이 아니다. 고객의 불편은 화면이 멈춰서 애니메이션 스티커를 포함한 댓글을 쓸 수 없다는 것이다.

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

 이 내용을 합쳐서 다음과 같이 체인지 로그를 작성해 보자.

댓글에서 애니메이션 스티커 때문에 화면이 멈추는 문제를 해결했습니다. 이제 애니메이션 스티커를 정상적으로 댓글에 사용할 수 있습니다.

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

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

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

 체인지 로그에는 '한 일'을 적는다. 체인지 로그 자체가 원래 개발의 결과니까 한 일을 적는 것이 당연하다. 하지만 개발자에게는 잡아야 할 버그가 아직 남아 있고 연구해야 할 개선 사항도 있고 개발할 새 기능도 많다.

 고객 입장에서는 고객이 요구하거나 불평한 것이 이번 릴리스에 다 반영되지 않으면 다음 릴리스를 기다릴 수밖에 없다. 그래서 다소 귀찮기는 하지만 다음 릴리스 항목으로 검토하는 것이 있다면 중요한 것은 공개하는 게 좋다. 이전에 릴리스하면서 잡은 버그가 완벽히 해결됐는지, 새 기능은 어떤 것을 많이 사용하는지도 얘기하자.

 예를 들어, 다음은 카카오맵의 2018년 5월 11일 체인지 로그다. '주요 개선 항목' 다음에 '검토 중인 항목'을 추가했다.

링크 : http://kakaomap.tistory.com/176

Semantic Versioning(유의적 버전)

 체인지 로그를 쓰면서 버전을 올리는데, 고객은 버전을 보고 체인지의 범위나 중요성을 먼저 판단한다. 예를 들어 다음과 같이 세 가지 방식으로 버전을 올렸다고 하자.

1. 버전 1.2.2 → 1.2.3
2. 버전 1.2.2 → 1.3.0
3. 버전 1.2.2 → 2.0.0

 1번은 세 번쨰째 자리에서 버전을 올렸는데, 간단한 패치를 의미한다. 그래서 이전 버전(1.2.x)과 호환된다.

 2번은 두 번째 자리에서 버전을 올렸다. 이것은 새로운 기능을 추가했을 때 1.3.0은 1.2.x와 일 부 호환될 수 있으나 새로운 기능을 1.2.x에서 사용할 수는 없다.

 3번은 첫 번째 자리에서 버전을 올렸다. 이 경우는 전면적인 업그레이드여서 이전 버전과는 거의 호환되지 않는다고 볼 수 있다. 프로그램의 명맥은 잇겠지만 완전히 다른 프로그램이다.

 아직은 버전 번호를 올리는 단일 표준이 없다. GitHub의 공동창업자인 톰 프레스턴 베르너가 정한 Semantic Versiong을 참고하면 좋다.

링크 : https://semver.org/lang/ko/

유의적 버전 2.0.0

 몇 가지 중요한 내용만 소개하면 아래와 같다.

• 버전은 X,Y,Z의 형태로 한다. X,Y,Z는 자연수로서 각각 독립적으로 증가한다. X,Y,Z를 구분하는 점(.)은 소수점이 아니라 구분 기호다. 따라서 1.1.12는 1.1.9보다 높은 버전이다. X를 Major, Y를 Minor, Z를 Patch로 간편하게 이해해도 좋다.
• X가 0인 것은 초기 내부 개발에서만 사용하고, 최초 공개 API는 1.0.0이어야 한다. X는 기존 버전과 호환되지 않는 변화가 있을 때만 1씩 올린다.
• Y는 기존 버전과 호환되는 새로운 기능이 추가됐을 때 1씩 올린다. 큰 규모의 패치가 있을 때 작은 규모의 패치와 구분하기 위해 Y를 올릴 수도 있다. 만약 X를 올리면 Y는 0으로 초기화돼야 한다. 단, 최초의 내부 개발 버전은 0.0.0이 아니라 0.1.0이다. 즉, 개발의 시작은 새로운 기능의 시작이므로 Y가 0이 아니라 1이어야 한다.
• Z는 기존 버전과 완전히 호환되면서 작은 규모의 패치가 있을 때 1씩 올린다. X나 Y를 올리면 Z는 0으로 초기화돼야 한다.
• 정식 배포 전에 사전 배포(프리 릴리스, pre-release)가 필요할 때는 Z 다음에 붙임표(-)로 구분하고 적절한 식별자를 적는다. 예를 들어 알파 버전이라면 1.0.0-alpha로 쓴다. 알파 버전이 여러 개라면 1.0.0-alpha.1처럼 점(.)으로 구분하고 숫자를 덧붙인다.
• 일단 배포된 버전은 변경해서는 안 된다. 변경이 있다면 무조건 버전을 올려야 한다.

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

---

문제와 문제점을 구별하자

 버그를 잡거나 새로운 기능을 추가하거나 성능을 개선하는 것은 모두 어떤 문제를 해결하기 위해서다. 이때 문제는 목표와 현상의 차이다. 목표는 있어야할 모습, 바람직한 상태, 기대되는 결과다. 현상은 현재의 모습, 예상되는 상태, 예기치 못한 결과다. 문제를 해결한다는 것은 목표에 다다르지 못하는 문제를 해결함으로써 현상을 목표에 일치시키는 것이다. 이러한 문제에는 발생형, 탐색형 설정형의 세 가지 종류가 있다.

 발생형 문제는 우리 눈앞에 발생해 당장 걱정하고 해결하기 위해 고민하는 문제다. 어떤 기준을 일탈하거나 미달해서 생기므로 원상 복구가 필요하다. 프로그램 에러가 대부분 발생형 문제다.

 탐색형 문제는 현재 상황을 개선하거나 효율을 높이는 문제다. 이 문제는 눈에 잘 보이지 않으므로 그냥 놓아두면 뒤에 큰 손실이 따르거나 해결할 수 없는 문제로 커진다. 프로그램 개선이나 시스템 효율화가 대부분 탐색형 문제다.

 설정형 문제는 미래 상황에 대응하는 문제다. 앞으로 어떻게 할 것인가 하는 문제다. 지금까지 해오던 것과 관계없이 새로운 과제나 목표를 설정함으로써 일어나는 문제다. 새로운 기능이나 대폭적인 업그레이드가 대부분 설정현 문제다.

 

 여기서 문제와 문제점을 구별해야 한다. 문제를 발생시키는 현상은 여러 가지다. 그 여러 가지 현상은 서로 상관관계나 인과관계를 맺기도 한다. 다음 예를 들어보자.

술을 많이 마시면 간이 상하고 몸속 비타민과 무기질이 소모되어 피로가 쉽게 풀리지 않고 일에 집중할 수도 없어서 생산성이 떨어진다.

 이 예에서 문제는 생산성이 떨어진다는 것이다. 이 문제를 발생시키는 현상을 도식화하면 아래와 같다.

술과 생산성

 이제 해결할 문제점을 선택해야 한다. 기업 입장에서 직원이 술을 많이 마시는 문제점을 해결하려고 하면 술을 끊도록 유도하거나 회식 자리를 줄이는 방법이 있다. 직원의 간이 상하는 문제점을 해결하려고 하면 건강검진을 꾸준히 받도록 해서 간 수치를 점검하게 하는 방법이 있다. 직원이 출근했을 때 전날 쌓인 피로가 쉽게 풀리지 않는 문제점을 해결하려고 하면 출근할 때 피로회복제를 무료로 나눠주는 방법이 있다.

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

 하나의 문제에 문제점은 여러 가지이고, 여러 가지 문제점을 모두 해결하기에는 예산과 인력이 늘 부족하므로 특정 문제점을 선택할 수밖에 없다. 그러므로 어떤 문제점을 선택하느냐에 따라 문제 해결 방법은 완전히 달라진다.

 릴리스 문서는 결국 개발자가 문제점 하나를 선택해서 해결한 결과다. 따라서 여러 문제점 중에 어떤 문제점을 선택했는지를 독자에게 정확히 알려줘야 한다.

 

 예를 들어 사용자가 급증하면 서버가 멈춘다고 하자. 문제는 서비스가 정상 작동을 하지 않은 것이다. 사용자 급증은 문제점이 아니다. 개발자가 사용자를 줄일 수 없기 때문이다. 문제점은 시스템의 잘못된 설정이나 최적화되지 않은 프로그램, 잘못된 DB 설계 등일 수 있다. 이때 개발자는 시스템 설정을 바꾸거나 프로그램을 최적화하거나 DB를 재설계할 수 있다. 하지만 이 모든 것을 동시에 다 할 수 없어 시스템 설정만 바꿨다고 하자. 그러면 이 사실을 릴리스 노트에 다음과 같이 쓸 수 있다.

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

 이것을 릴리스 노트에 다음과 같이 서술할 수 있다.

OOO 서비스에 사용자가 급증하면 OO 서버가 정지하는 문제는 시스템 재설정으로 해결했습니다. 추후 프로그램 최적화와 DB 재설계도 검토하겠습니다.

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

 릴리스 노트는 고객에게 보고하는 문서인 만틈 계약에 의한 산출물로 취급될 수도 있다. 실제 재판에서 재판관이 릴리스 노트를 계약서에 준하는 문서로 판단할 수 있다. 따라서 개발자가 주로 쓰고 완성하는 릴리스 노트에는 개발자의 법적 책임을 줄일 수 있는 내용, 즉 면책 조항을 꼭 적는 것이 좋다.

 

장애 보고서

---

장애 보고서는 보통의 개발 문서와 크게 달라서 장애 보고서의 특성을 잘 이해해야 한다. 장애 보고서의 특성을 하나씩 짚어보자.

 

 첫째, 장애 보고서는 개발자가 원할 때 쓸 수 없다. 장애를 해결하면서 동시에 신속하고 계속적인 장애 보고 지시에 늘 시달린다. 그래서 무엇보다 신속한 글쓰기가 필요하다.

 둘째, 장애의 1차 원인은 대부분 다른 원인의 결과다. 장애의 원인을 정확히 알아내려면 원인의 원인을 계속 찾아 나가야 한다. 더는 원인의 원인을 찾을 수 없을 때 그 원인이 장애의 최초 원인이다. 그런데 장애의 재발을 막으려면 원인만 핵셜해서는 안 된다. 그 원인이 발생한 이유를 알아야 한다. 이유는 사람에게 있다. 원인과 이유를 찾는 분석적 글쓰기가 필요하다.

 셋째, 장애 보고를 받는 윗사람은 대부분 개발자가 아니다. 특히 인문계 출신 임원은 장애를 곧 비즈니스에 주는 영향으로 본다. "그래서 손해가 얼마인가요?"라고 묻는다. 그래서 그들과 소통하기 위한 비즈니스 관점의 글쓰기가 필요하다.

 넷째, 장애를 해결했다고 해서 100% 해결한 것은 아니다. 장애란 것이 원래 예상하지 못한 데서 발생한 것이니, 지금 어떤 처치를 했다고 해서 다시는 재발하지 않는다고 확정할 수 없다. 하지만 윗사람들은 늘 확정적인 대답을 원하고 애매한 표현을 싫어한다. 그래서 윗사람에게 보고할 확정적이고 신뢰할 만한 결단으로 정치적 글쓰기를 해야 한다.