Technical Writing, 에러 메세지 잘 남기는 법

Swift 공부도 좋지만, 가끔은 다른 글도 써볼겸 오늘은 테크니컬 라이팅 관련 글을 가져왔다.

사용자에게 서비스를 하는 개발자들이라면, 에러 메세지의 중요성을 모르진 않을거라고 생각한다.

실제로 어떤 메세지를 제공해주느냐에 따라서 CS로 발전하기도 하고, 사용자들 스스로가 해결하고 마무리하기도 한다.

프로젝트 진행 시에도, 사용 사례를 고려하지 않은 키오스크 메세지들을 수정해서 CS를 줄였던 적이 있는 만큼 다시 한 번 되새기기 위해 주제를 선정하였다.

---

구글에서 이야기하는 좋은 에러 메세지를 작성해야 하는 이유이다.

Bad error messages frustrate users. Good error messages provide critical information when things are not working as expected. Error messages are often the main way developers interact with users when problems occur. Some error messages are caused by invalid user inputs or misuse of certain features and some are caused by product defects; all error messages require users to figure out what to do next.

 

오류가 발생하는 시점에 개발자가 사용자와 상호작용 할 수 있는 수단, 잘 작성해야 사용자로 하여금 좋은 경험을 만들어 줄 수 있을 뿐 아니라, 잘 만들어진 오류 메세지는 사용자로 하여금 문제 해결 방법을 제공해 줄 수 있지만 아니라면 오히려 혼란을 가중시킬 수 있음

 

잘 작성된 오류메세지?

사례를 본격적으로 달기 전에, 구글에서 정의한 잘 작성된 오류 메세지들의 공통적인 특징은 다음과 같다.

• 실행 가능
• 좋은 사용자 경험 제공
• 적은 작업량, 신속한 문제 해결
• 사용자가 스스로 다음 행동을 취할 수 있음

즉, 사용자에게 간단한 다음 동작을 제시하고 직면한 문제를 해결 할 수 있도록 하는 에러 메세지가 잘 작성된 것이라고 볼 수 있겠다. 다음으로는 좋은 메세지를 위한 오류 처리 규칙들을 정의 해놓았는데, 텍스트가 많아 원문 보다는 개인적으로 요약한 내용들 위주로 담았다.

 

조용히 실패하지 않을 것

잘못 될 수는 있지만, 잘못된 후에도 개선되지 않는 것은 정말 큰일이다.

• 오류가 발생했음을 알아야 할 필요성이 있는데, 조용히 아무 일도 일어나지 않는 것은 매우 위험한 상황
• 인간이 만드는 소프트웨어인 만큼 항상 오류가 발생할 수 있음을 인지하기
• 오류가 발생하는 것이 필연적이라면, 오류가 발생했음을 알게 만드는 것도 중요한 일
• 오류를 알림으로서 개선할 기회를 얻고, 사용자들에게 더 좋은 경험을 제공할 수 있음
  
  

프로그래밍 언어 가이드를 따르는 것도 한 방법

아래는 실제로 구글에서 사용하고 있는 각 언어별 코드 스타일 가이드이다.

뜯어서 보는 건 처음이긴 한데 텍스트는 많지만 단락별 내용이 많지 않아 금방금방 읽고 적용해 볼 수 있다.

• https://google.aip.dev/193
• https://github.com/googleapis/api-common-protos/blob/main/google/rpc/code.proto
• https://google.github.io/styleguide/cppguide.html 
• https://google.github.io/styleguide/javaguide.html 
• https://google.github.io/styleguide/pyguide.html 
• https://google.github.io/styleguide/jsguide.html

 

자세한 원인을 명시할 것

서버 오류는 정말 다양한 이유로 발생할 수 있는 만큼 명확하게 알려주어야, 사용자 혹은 개발자가 이를 대응할 수 있게 된다.

• 서비스 실패
• 네트워크 연결 끊김
• 권한 문제

‘서버 오류’라는 메세지는 사용자가 에러를 느껴도 다음 행동을 취하는데 도움을 줄 수 없으므로 사용자로 하여금 다음 행동을 결정 할 수 있을 정도로는 제공해주는 것이 좋다고 볼 수 있다. 이게 잘 안되면, CS의 영역으로 넘어와서도 개발자와 사용자간 소통이 추가적으로 필요해지기도 하고 찾아서 추적하는 비용도 꽤나 발생하게 된다.

 

개인적으로 정말 중요한 부분이라고 생각하는데,  동일한 오류를 보고 모든 사람들이 똑같이 식별하지 않는다는 것이 매번 어려운 부분이었다. 정확하게 맞춰진 메세지가 있으면, 이를 기반으로 추적하고 수정 및 대응할 수 있지만 간략한 에러메세지를 제공해주는 경우 보통은 사용자가 느끼는 의견들이 더해져서 개발자에게 전해지는 경우가 많았다.

이로 인해 오히려 식별이 어려워 지는 경험을 많이 했던 만큼 여러 파트 중 제일 중요한 부분이라고 사견을 더해본다.

 

오류는 즉시 알릴 것

오류를 일괄적으로 관리하기 위해, 발생 시점이 아닌 다른 곳에서 알리기 시작하는 순간 개발 생산성이 감소하게 된다.

다른 것 보다 이를 찾고 확인하는 시간이 늘어나기 때문에, 가능하다면 발생하는 지점에서 바로 알려주는 것이 좋다.

 

에러 코드 기록하기

에러 코드는 모니터링하고 진단하는데 큰 도움을 주는 만큼 코드를 만들어서 지정해 주는 것이 좋다.

적절한 에러 코드를 엔지니어링 과정에서 지정해두면, 엔지니어나 담당자가 쉽게 찾고 디버깅 할 수 있다.

구글에서 권장하기를 사전에 정의된 코드들을 만들고 이에 따른 응답 모델과 같은 것을 제공함으로서 개발자들이 개발하는 데에 있어 일괄적인 대응을 할 수 있도록 하는 것이 생산성에 도움이 된다고 한다.

---

오류 메세지 작성법

다음으로는 이러한 규칙들을 기반으로 권장하는 오류 메세지 작성법이다.

 

• 오류 원인 전달, —를 하려했지만 —때문에 진행되지 않았고 —하면 할 수 있습니다
• 올바르지 않은 입력 전달, 우편번호는 5자리 혹은 6자리여야 합니다
• 요구사항, 제약사항 명시, 입력된/제공된 —의 크기가 제한(—)을 초과합니다
• 해결 방법과 예시 제공, 해당 버전의 어플리케이션엔 오류가 있고, 업데이트를 눌러서 진행해주세유
• 간결하고 명확하게, 단어를 좀 줄일 필요성이 있다
• 이중부정 금지, 모호하게 작성하면 안됨
• 사용자를 위한 단어 선택, 개발자로서 많이하는 실수 중 하나가 개발자 언어로 설명해서 이해하길 바라기
• 일관된 용어 사용, 처음 정한 단어로 계속 설명해주기
  
  

쉽게 적용해 볼 수 있는 포맷

• 상세 문서를 제공해주기
  사용자로 하여금 더 알아보기 위해 선택 할 수 있는 링크를 제공해주기
• 점진적인 메세지 전달
  짧은 메세지를 먼저 제공해주고, 사용자가 원한다면 긴 메세지를 확인 할 수 있도록 하기
  긴 글에는 거부감이 드는 사람이 많음
• 오류와 가까운 곳에 메세지 배치
  오류를 보고 수정까지의 생각을 줄여주자
  오류가 난 지점 근처에서 메세지를 확인 할 수 있도록 해주기
• 신중한 색상 배치
  색상으로 강조를 하는 경우에도 이를 유의해서 사용해야 함
  색맹의 비율이 생각보다 높다고 한다.

올바른 어조, TPO

• 긍정적인 어조 사용하기, 무언가를 지적하는 것 보다, 해결 방법을 우선적으로 이야기하기
• 불필요한 미안함, ****미안함을 이야기 할 시간에 문제 설명과 해결방법 제시하기
• 불필요한 유머, 에러로 문제가 생긴 상황에서 이상한 유머를 넣을 생각하지 말기
• 비난 금지, 원인보다는 해결법에 초점 맞추기

머리로는 항상 이해하고 있던 부분인데, 실제로 적용하다 보면 놓치기 쉬운 내용들이 아닐까 싶다.

오늘도 문서를 보며 하나 반성하게 되는 하루가 되었다.

 

참고 문서

https://developers.google.com/tech-writing/error-messages

Writing Helpful Error Messages  |  Technical Writing  |  Google Developers