개발자의 글쓰기2

3장. 사용자와 소통하는 에러 메시지 쓰기

01. 에러 메시지를 쓰기 전에 에러부터 없애자

• 404 에러가 죄송할 일인가?

사용자가 404 에러 페이지를 만나는 경우는 다음과 같이 두 가지 밖에 없다.

1. 사용자가 URL을 잘못 입력한 경우
2. 사용자가 링크를 클릭했으나 해당 페이지가 없는 경우

1번 케이스는 사용자가 URL을 잘못 입력한 것이라서 사용자의 문제이다.
2번 케이스는 링크가 있어서 클릭했는데 해당 페이지가 없는 경우다.
이것을 깨진 링크, 또는 죽은 링크, 나쁜 링크라고 한다.
문제는 이런 깨진 링크를 개발자들이 내버려 두는데 있다.

• 깨진 링크는 개발자의 책임이다.

깨진 링크를 찾아내는 서비스를 이용하면 금방 확인할 수 있다. (브롱큰링크체크닷컴)

사이트 안에서 링크로 연결되다 깨진 것도 문제지만 요즘은 다른 사이트에서 연결된 링크가 깨진 경우가 더 큰 문제다. 특히 검색 엔진이 페이지를 수집했는데, 이후에 페이지 URL이 바뀌거나 페이지를 삭제했는데도 검색엔진에 원래 페이지를 그대로 갖고 있다가 링크로 연결하는 경우가 있다.

이떄는 검색 엔진마다 제공하는 도구를 사용하면 깨진 링크를 없앨 수 있다.

** webpoc 쪽에도 깨진 링크 호출하는 케이스가 있는데, 정리가 필요함.

• 개발자용 에러 메시지와 사용자용 에러 메시지를 분리하자

** 서버 개발 쪽에서는 exception message 값을 클라에서 그대로 사용하는 경우도 있으니, exception message 값 설정 시, 주의해야함.

02. 사용자 에러 메시지를 제대로 쓰는 법

• 사용자 에러에 대처하는 메시지

사용자 에러가 발생하면 알림창을 이용해 에러가 발생했음을 알리는 메시지를 보여줘서 사용자가 바른 행동을 하도록 유도한다.

사용자 에러 메시지에는 에러의 내용, 에러의 원인, 에러 해결 방법이 포함돼야 한다.

• 에러 메시지를 보여주는 순서

에러 내용과 원인이 간단해서 내용, 원인, 해결방법 순으로 보여줄 수 있지만
원인 내용과 원인이 복잡한 경우, 해결 방법, 원인, 내용 순으로 바꾸는 것이 더 좋다.

줄 바꿈을 적절히 활용하는 것도 좋은 방법이다.

에러 내용과 원인을 합쳐서 쓰다 보면 문장이 복문이 되어 매끄럽지 않을 때가 많다.
이떄는 에러 내용을 없애고 원인만 간단히 써도 해결 방법이 먼저 나오기 때문에 사용자가 충분히 내용을 이해할 수 있다.

• 오락가락 메시지와 버튼 메시지

가능하다면 '취소'라는 말보다 더 구체적인 행동을 말로 전하는 것이 좋다.
짧고 애매한 것보다는 길더라도 분명한 것이 더 낫다.

03. 사용자의 에러를 줄이는 메시지 구조화

• 버튼의 순서

확인 - 취소 순서가 OS에 따라 뒤죽박죽이다.
따라서, OS의 순서를 따르는 것보다는 서비스 내에서 일관성을 가지는 것이 좋다.

앞에서 말했지만 확인, 취소 대신 '삭제하고 이동하기', '이 페이지에 머물기' 처럼 구체적인 행동을 적는 것도 좋은 방법이다.

필요하다면 시각적으로 강조하는 것도 좋다.

• 사용자의 반복 에러 막는법

계속 로그인을 실패하면 자동 입력 방지 문자를 입력할 것을 요구하거나, 남은 로그인 횟수를 메시지로 보여부면 어떤 사용자든 자기 행동을 주의하게 된다.

04. 에러 메시지 대신 예방 메시지를 쓰자

• 서비스를 이해하면 에러를 예방할 수 있다.

사용자가 어떻게 사용할지를 충분히 이해하고 조사하고 분석해야 에러를 줄일 방법을 찾을 수 있다.

ex) 호텔 예약 사이트에서 오늘 이전 날짜는 선택할 수 없도록 비활성화 처리

• 닭이 먼저? 알이 먼저?

개발자도 자신만의 철학을 가져야 한다.

사용자의 모든 행위를 불완전하므로 검증하는 방안으로 개발을 할지,
사용자에게 어느정도 책임을 부여하고 믿고 예방만 하는 방안으로 개발할지

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

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

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

체인지 로그는 간단히 쓰면 할 일이 없어 보이고 자세히 쓰면 아무도 읽지 않아 쓸모가 없다.
체인지 로그를 적절한 양으로 쓰려면 일단은 체인지 로그를 최대한 많이 써야 한다.
그 다음에는 일정한 기준으로 선정하고 비슷한 것끼리 분류한 뒤 문장을 요약하는 기술이 필요하다.

1. 선정하기
   체인지 로그는 회사의 공식 발표이며, 독자와 직접 소통하는 문건이다.
   회사, 개발자, 독자의 관심을 가지고 8가지 경우로 분류해 체인지 로그를 선정하고 순위나 수준을 결정할 수도 있다.

2. 분류하기
   공개할 체인지 로그를 선정했으면 비슷한 체인지 로그끼리 묶어야 한다.

3. 요약하기
   서술식 문장을 개조식 문장으로 바꾸는 방법을 쓰면 내용이 자연스럽게 축약되고 의미는 더 분명해진다.

4. 종합하기
   릴리즈 내용 전체를 종합해서 한 문장으로 만들고 그것을 체인지 로그 첫 줄에 적어야 한다.

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

• 개발자 관점과 고객 관점

체인지 로그는 개발자가 변경한 내용을 적은 것이다.
체인지 로그를 보는 독자는 뭔가 새로운 것, 바뀐 것, 그래서 자기에게 좋거나 유익하거나 어떤 행동을 해야 할지 명확하게 지시하는 것을 보고 싶어 한다.

체인지 로그를 하나의 관점으로만 쓸 필요는 없다. 내용에 따라 관점을 적절히 선택하는 것이 중요하다.

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

다음 릴리스 항목을 검토하는 것이 있다면 중요한 것은 공개하는 것이 좋다.

• Semantic Versioning(유의적 버전)

1. 버전 1.2.2 -> 1.2.3 : 간단한 수정
2. 버전 1.2.2 -> 1.3.0 : 새로운 기능 추가
3. 버전 1.2.2 -> 2.0.0 : 강제 업그레이드 수준

버전 번호를 올리는 단일 표준이 없기 때문에 톰 프레스턴 베르너가 정한 Semantic Versioning 을 제시한다.

• 참고 : https://spoqa.github.io/2012/12/18/semantic-versioning.html

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

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

체인지 로그는 몇 줄로 간단히 쓰지만 릴리스 문서는 정식으로 작성하여 고객에게 제공된다.
단순히 정보 제공 하는 것을 넘어서 고객에게 제공하는 문제 해결 보고서라고 할 수 있다.

문제와 문제점을 정리하고, 해결할 문제점을 선택해서 개선해야 한다.

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

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

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

릴리스 노트는 이처럼 문제, 문제점, 해결책, 후속 계획 순서로 쓰는 것이 좋다.
그래야 고객이 릴리스 노트의 내용을 정확히 파악할 수 있고 향후 변경 계획도 짐작할 수 있다.

• 법적인 문제를 고래해서 쓰자

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

예를 들면, 다음과 같은 항목이 반드시 포함돼야 한다.

1. 문서정보 : 제품명, 릴리스 이름, 릴리스 버전, 릴리스 날짜등
2. 개요 : 릴리스 노트의 주요 내용을 종합한 글
3. 새로운 기능
4. 개선 사항
5. 버그 수정
6. 영향과 주의사항 : 릴리스로 인한 영향과 개발자의 주의사항
7. 연락처
8. 면책 : 변경 사항이나 릴리스 문서로 인한 법적 문제 발생 시 책임의 한계에 관한 내용

개발자에게 면책은 개발의 한계이자 도전 대상이다.

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

• 장애 보고서의 특징

장애 보고서를 쓸 사람은 개발자 말고는 없어서, 개발자가 장애도 고치고 보고도 해야한다.
장애 고치랴 보고서 쓰랴 정신이 없다. (ㅇㅈ..)

장애 보고서란 것이 보통의 개발 문서와 크게 달라서 장애 보고서의 특성을 충분히 이해하고 쓰지 않으면 쓸모가 없다.

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

장애 발생해서 인지한 순간부터 장애 해결 직후나 다음날 오전까지 장애 보고서를 쓰는 시간이다.
그래서 무엇보다 신속한 글쓰기가 필요하다.

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

원인의 원인을 계속 찾아 나가야 장애의 원인을 정확하게 알아낼 수 있다.
원인의 원인을 찾을 수 없을 때 그 원인이 장애의 최초 원인이다.

장애의 재발을 막으려면 원인만 해결해서는 안 된다.
그 원인이 발생한 이유를 알아야 한다.
이유는 사람에게 있다.
원인과 이유를 찾는 분석적 글쓰기가 필요하다.

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

장애를 비즈니스에 주는 영향으로 보기 때문에 비즈니스 관점의 글쓰기가 필요하다.

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

확정적이고 신뢰할 만한 결단을 정치적으로 내려야 한다.
그래서 정치적 글쓰기가 필요하다.