fkdl0048 / BookReview

It's a repo that reads and organizes books
MIT License
7 stars 0 forks source link

4장: 독자 관점에서 릴리스 문서와 장애 보고서 쓰기 #289

Closed fkdl0048 closed 1 month ago

fkdl0048 commented 1 month ago

4장: 독자 관점에서 릴리스 문서와 장애 보고서 쓰기

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

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

어떤 일이든 하고 나서 그 일의 내용을 상사나 고객에게 글로 보고해야 할 때가 있다. 이때 체인지 로그를 작성하는데 너무 적거나 너무 많아도 좋지 않다. 읽기 좋게 적절한 양으로 써야 상사도 고객도 만족한다.

체인지 로그를 적절한 양으로 작성하기 위해서는 일단은 체인지 로그를 최대한 많이 써야 한다. 그다음에는 일정한 기준으로 선정하고 비슷한 것끼리 분류한 뒤 문장을 요약하는 기술이 필요하다.

1단계: 선정하기

체인지 로그의 양을 줄이려면 체인지 로그 중에서 쓸 것과 없앨 것을 구분하는 기준이 필요하다. 이때 개발자는 보통 자기가 오랜 시간을 들여 노력한 것을 쓰고, 그렇지 않은 것은 빼는 경향이 있다. 하지만 이런 기준으로 체인지 로그를 선정해서는 안 된다. 체인지 로그를 보는 사람의 입장은 다 다를 수 있기 때문이다.

실제로 따로 회사에서 표를 만들어 우선순위를 분류하거나 상황에 맞게 선정하는 방법을 사용하기도 한다.

2단계: 분류하기

공개할 체인지 로그를 선정했으면 비슷한 체인지 로그끼리 묶어야 한다. 이 때 두 가지 방법이 있다. 첫 번째 방법은 개발 관점에서 비슷한 작업으로 묶는 방법으로, 독자가 개발자인 경우 유용하다. 두 번째 방법은 독자가 일반 사용자인 경우에 유용하다.

두 방법의 차이는 개발 관점에서는 기능별로 묶는 것이고, 사용자 관점에서는 사용자가 느낄 수 있는 변화를 묶는 것이다.

3단계: 요약하기

체인지 로그를 분류했으면 문장 단위로 요약할 차례다. 여러 가지 요약 방법중에서 서술식 문장을 개조식 문장으로 바꾸는 방법을 쓰면 내용이 자연스럽게 축약되고 의미는 더 분명해진다. 개조식 문장을 만드려면 불필요한 부사나 형용사, 조사나 어미를 없애고, 정확하고 적절한 단어로 대체하면 된다.

4단계: 종합하기

체인지 로그는 결국 이전과 비교해서 핵심적으로 뭐가 달라졌는지 명확하게 보여줘야 한다. 릴리스 내용 전체를 종합해서 한 문장으로 만들고 그것을 체인지 로그 첫 줄에 적어야 한다. 전체를 종합하는 방법은 분석과 반대디.

종합이 분석과 반대라는 말은 "토끼는 동물이다"처럼 개념화하지 않고 "토끼는 귀가 밝다"처럼 특성으로 서술하거나 "토끼는 잘 도망간다"처럼 결과로 서술하거나 "토끼는 귀가 밝아서 잘 도망간다"처럼 특성과 결과를 합쳐서 서술하는 것이다.

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

개발자 관점과 고객 관점

체인지 로그는 개발자가 변경한 내용을 적은 것이다. 하지만 체인지 로그를 보는 독자는 뭔가 새로운 것, 바뀐 것,그래서 자기에게 좋거나 유리하거나 어떤 행동을 해야할지 명확한 정보를 원한다. 물론 체인지 로그가 개발자끼리 공유된다면 한일만 적어도 상관없다.

만약 체인지 로그가 고객에게 공개 예정이라면 해당 체인지 로그는 고객 관점으로 작성되어야 한다. 다음과 같은 체인지 로그를 보자.

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

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

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

이를 고객의 문제 해결로 변경하면 다음과 같다.

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

또한, 체인지 로그를 꼭 하나의 관점으로 쓸 필요는 없다. 내용에 따라 관점을 적절히 선택하는 것도 중요하다. 소소한 것이라면 따로 기타로 묶어라. (예를 들어 첫 문장은 사용자 관점의 문제 해결, 두 번째 문장부터는 개발자 관점의 문제 해결)

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

체인지 로그 자체가 원래 개발의 결과니까 한 일을 적는 것은 당연하다. 하지만 아직도 잡아야 할 버그가 남아 있거나 연구 또는 개선 사항이 넘친다. 고객 입장에서도 이전에 해결된 문제가 다시 발생하지 않는지, 미래에 또 다른 문제가 발생하지 않을지 궁금할 것이다.

다소 귀찮지만, 이후 개발 예정인 항목에 대해서 어느정도 공개하는 것이 좋다.

Semantic Versioning (유의적 버전)

이는 유명한 버전 관리 방법으로, 버전을 통해 어떤 변화가 있었는지 알 수 있게 한다. 버전은 다음과 같이 구성된다.

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

문제와 문제점을 구별하자

체인지 로그는 간단하게 작성할 때가 많지만 만약 소프트웨어를 파는 기업SI라면 문서를 정식으로 만들어서 고객에게 제공해야 한다. 이때 릴리스 문서는 단순히 정보를 제공하는 것을 넘어서 고객에게 제공하는 문제 해결 보고서라고 할 수 있다.

버그를 잡거나 새로운 기능을 추가하거나 성능을 개선하는 것은 모두 어떤 문제를 해결하기 위해서다. 이때 문제는 목표와 현상 차이다. 목표는 있어야할 모습, 바람직한 상태, 기대되는 결과다. 현상은 현재의 모습, 예상되는 상태, 예기치 못한 결과다.

문제를 해결한다는 것은 목표에 다다르지 못하는 문제를 해결함으로써 현상을 목표에 일치시키는 것이다. 이러한 문제에는 발생형, 탐색형, 설정형의 세 가지 종류가 있다.

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

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

설정형 문제는 미래 상황에 대응하는 문제다. 앞으로 어떻게 할 것인가 하는 문제다. 지금까지 해오던 것과 관계없이 새로운 과제나 목표를 설정함으로써 일어나는 문제다. 새로운 기능 추가나 새로운 시스템 구축이 대부분 설정형 문제다.

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

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

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

위 내용으로 릴리스 문서를 작성하면 다음과 같다.

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

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

릴리스 노트의 핵심은 문제 해결의 과정과 결과를 고객에게 알려주는 것이다. 여기에 덧붙여 노트도 보고서의 일종인 만큼 형식도 갖춰야 한다.

이런 문서인 만큼 법적인 문제를 피하기 위해 면책 조항을 작성하는 것이 좋다. (너무 강압적이지 않게)

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

장애 보고서의 특징

고객사 서비스 운영을 대행하는 개발자가 가장 싫어하는 것이 장애보고서 작성이다. 장애 보고서의 특징들을 알아보자.

요약하자면 장애 보고서를 작성할 때는 다음과 같은 글쓰기 기법이 필요하다.

  1. 질문에 대답하는 신속한 글쓰기
  2. 원인과 이유를 찾는 분석적 글쓰기
  3. 상사를 고려하는 비즈니스 관점의 글쓰기
  4. 원하는 것을 얻는 정치적 글쓰기

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

글을 빨리 쓰는 방법 중에 대화를 글로 옮기는 방법이 있다. 가까운 동료와 대화할 때 우리는 깊이 생각하느라 한참을 뜸 들이거나 할 말을 정하지 못해서 말을 안하는 경우는 없다. 일단 무슨 말이든 내뱉고 나서 생각을 정리하고, 질문 받으면 답하면서 다음 생각으로 이어진다. 이 방법을 글쓰기에 그대로 적용하면 신속하게 글을 쓸 수 있다.

우선 장애를 아주 단순하게 주어, 목적어, 서술어로만 쓰자

"사용자가(주어) 결제를(목적어) 할 수 없다.(서술어)."

이후 이 문장에 동료가 답한다고 생각하고 아는 대로 말로 대답하듯이 작성한다.

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

문제 해결 기법 중에 5Whys가 있다. 이것은 어떤 문제의 원인을 찾을 때 피상적인 원인이 아니라 근본적인 원인을 찾는 기법이다. 문제의 원인이 되는 인과 관계를 탐색할 때 다섯 번 반복해서 원인이 무엇인지 질문하는 방식이다.

반복해서 "왜?"라고 질문함으로써 근본 원인을 찾는 것이다. 여기서 Why는 두 가지 뜻으로 이해해야 한다. 첫째는 사물이나 현상, 동작이 문제를 초래하는 원인, 둘째는 사람이 문제를 초래한 이유다. 원인은 어떤 일이나 사건이다. 이유는 사람이 어떤 일을 하거나 하지 않은 까닭이나 동기다. 즉, why는 어떤 일 또는 사람이다.

IT업계에서 장애는 대부분 재발한다. 재발하는 원인은 시스템 자원이 늘 부족하기 때문이기도 하지만, 대부분 사람의 문제다. 즉 개발자 사이의 커뮤니케이션 오류가 바로 핵심이다.

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

"가진 것이 망치뿐이면 모든 것이 못으로 보인다"라는 말처럼 각자 자기 위치와 입장에서 최선을 다하는 것뿐이다. 즉, 각자의 입장을 이해하고 이 사실을 인정해라. 그래야 윗사람에게 보고할 때 그들과 같은 비즈니스 관점에서 할 수 있다.

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

장애는 보통 예상하지 못한 곳에서 발생한다. 그리고 장애를 해결했다고 다시 발생하지 않을 보장도 없을 뿐더러 재발할 때마다의 미묘한 차이가 있다. 이런 경우엔 설명하기 너무 어렵고 애매할 때가 많다.

따라서 어느정도 정치적인 글쓰기 기법이 필요하지만, 회사의 경우엔 이를 명확하게 전달하는 것이 더 중요하다.