구글이 제안하는, 최적화된 오류 메세지 작성하기

소프트웨어 엔지니어들은 매일, 그리고 매 번 문서를 포함하여 다양한 글을 작성합니다. 메신저, 이메일, 일일 보고서, 코드, 그리고 심지어 코드 사이의 주석까지 다양한 범주를 아울러 글을 작성합니다. 팀원들과의 원활한 의사소통을 하거나 정보를 나누기 위해서 잘 작성된 문서는 엔지니어들의 업무 환경의 질을 향상시킵니다. 따라서 Technical Writing은 엔지니어링 영역의 중요한 부분 중 하나입니다.

 

구글은 공학자들의 Technical Writing 능력 향상을 위해서 공식 사이트에서 교육 자료를 공유합니다. 해당 포스팅에서는 구글의 공식 사이트의 한 부분인 Writing Helpful Error Messages를 다룹니다. 해당 포스팅은 오류 메세지를 효율적이고 생산적인 방식으로 작성하는 것을 주로 다룹니다.

 

 

잘 작성된 오류 메세지가 중요한 이유

잘못된 오류 메세지는 사용자들을 혼란스럽게 만듭니다. 잘 작성된 오류 메세지는 잘못된 지점을 예상할 수 있게끔 중요한 정보를 제공합니다. 오류 메세지는 개발자들이 오류를 접한 사용자들과 소통하는 주된 방식이기도 합니다. 불충분한 오류 메세지는 유효하지 않은 사용자의 입력 값이나 특정 기능을 저해하며 혹은 서비스의 결점을 야기시킬 수도 있습니다.

 

Google 은 좋지 못한 오류 메세지들을 통해서 유저들은 다음과 같은 문제를 야기한다는 것을 분석했습니다.

👉🏻 unactionable, vague, imprecise, confusing, inaccurate, unclear cause, unknown next steps

 

위와 상반된 방향으로, 소프트웨어 엔지니어들은 유저에게 아래와 같은 경험을 오류 메세지를 통해 전달해야 합니다.

 

- Deliver the best user experience: 최상의 유저 경험 User experience를 전달한다

- Are actionable : 행동을 취할 수 있게 만든다.

- Are universally accessible : 범용적으로 접근할 수 있다.

- Enable users to help themselves: 유저 스스로 해결할 수 있다.

- Redce the support workload : 작업양이 줄어든다.

- Enable faster resolution of issues : 더 빠른 이슈 해결을 가능하게 한다.

 

오류 메세지는 개발자와 유저들 사이의 주된 의사소통이기도 합니다. 소프트웨어 엔지니어는 '잘 작성된' 오류 메세지를 작성할 필요가 있습니다. 자세한 가이드를 하나씩 살펴보기 전에 오류 메세지를 작성할 때의 규칙을 먼저 살펴보도록 하겠습니다.

  

✔️ 오류를 즉시 발생시켜라

오류가 발생한 시점에 빠르게 발생하는 것은 굉장히 유용합니다. 오류를 붙잡고 있는 것은 굉장히 비효율적이며 디버깅 비용을 극적으로 증가시킵니다.

 

✔️ 실패를 조용하게 넘기지 마라

개발자는 소프트웨어의 실패를 피할 수 없습니다. 언제 어디서나 오류는 발생할 수 있으며, 소프트웨어를 설계할 때 오류 메세지를 계획해서 사용자 오용을 최소화 해야 합니다.

 

✔️ 오류의 근원이 묻히지 않도록 해라

오류의 근원(Root cause)을 포함해서 오류를 발생시켜야 합니다. 근원이 묻히지 않도록 조심해야 합니다. 넓은 범위를 의미하는 오류 메세지는 사용자들을 혼란시킵니다. 

 

✔️ 오류 코드를 기록하라

모든 오류 코드를 문서화하세요. 숫자화된 오류 코드는 사용자 지원과 모니터링, 오류 진단에 용이합니다.

 

 

 

위와 같은 규칙들을 기반에 두고 오류 메세지의 좋은 예시와 좋지 못한 예시를 확인하며, 적절한 오류 메세지 가이드를 살펴보도록 합니다.

 

 

최적화된 오류 메세지

항상 대상 독자를 생각하고 간결하고 명백하게 작성하는 것을 원칙으로 삼아야 합니다. 이는 Technical Writing의 핵심 사항임을 염두해두시길 바랍니다.

 

📌  오류의 원인을 전달하라

Identify the error’s cause

 

사용자에게 어떤 문제가 있는지를 확실히 전달해야 합니다.

 

❌ 잘못된 접근

✅ 해당 디렉토리가 존재하지만 쓰기 가능한 상태가 아닙니다.
해당 디렉토리에 파일을 추가하려면, 디렉토리를 쓰기 가능한 상태이어야 합니다.
[쓰기 가능한 상태로 만들 수 있는 방법에 대한 설명

❌ Invalid field 'picture'.

✅ The 'picture' field can only appear once on the command line; 
this command line contains the 'picture' field <N> times.
Note: Prior to version 2.1, you could specify the 'picture' field more than once, 
but more recent versions no longer support this.

 

 

 

📌 잘못된 입력 값을 전달하라

Identify the user’s invalid inputs

 

오류 메세지에 문제가 되는 값을 명시하여 사용자가 문제가 되는 부분을 알게 해야 합니다.

 

❌ 잘못된 우편 번호

✅ 한국의 우편 번호는 반드시 5자리의 숫자로 구성되야 합니다. 입력된 우편번호(284619)는 6자리의 숫자입니다.

❌ Funds can only be transferred to an account in the same country.

✅ You can only transfer funds to an account within the same country. Sender account's country (UK) does not match the recipient account's country (Canada).

 

 

만약 오류 메세지가 여러개라서 한 줄에 명시할 수 없다면 아래의 사항을 고려해볼 수 있습니다.

- 문제점들을 점차적인 방식으로 명시하세요. 버튼을 제공해서 유저의 클릭으로 리스트된 오류를 보여주도록  만드세요.

- 문제가 되는 입력 값을 모두 제거하고, 필요가 되는 부분만을 남기세요.

 

 

📌 요구 사항과 제약 사항을 명시하라

Specify requirements and constraints

 

요구 사항과 제약 사항은 명시해서 사용자가 오류가 발생한 이유를 이해하도록 만드세요. 사용자는 당신의 시스템의 제한을 모른다는 것을 명심하세요.

 

❌ 붙임 파일의 용량이 너무 큽니다.

✅ 붙임 파일의 용량(14MB)이 최대 허용 크기(10MB)를 초과했습니다. [접근 가능한 방식에 대한 추가 설명]

❌ Permission denied.

✅ Permission denied. Only users in <group name> have access. [Details about adding users to the group.]

❌ Time-out period exceeded.

✅ Time-out period (30s) exceeded. [Details about possible solution.]

 

 

📌 문제 해결 방안을 설명하라

Explain how to fix the problem

 

액션을 취할 수 있는 오류 메세지를 작성하세요.

문제가 되는 부분을 설명한 후에 문제를 해결할 수 있는 방안을 제안하세요.

 

❌ 해당 기기에서 X앱은 더 이상 지원하지 않습니다.

✅ 해당 기기에서 X앱은 더 이상 지원하지 않습니다. X앱을 업데이트하려면, 앱 내의 '업데이트' 버튼을 클릭하세요.

 

 

📌 예시를 제공하라

Provide examples

 

예시를 제공하여 사용자가 문제의 옳은 방향이 무엇인지 알게끔 안내하세요.

 

❌ 유효하지 않은 이메일 주소.

✅ 입력한 이메일 주소(gngsn)에 @ 표시와 도메인 이름이 누락되었습니다. 올바른 예시: gngsn@example.com.

❌ Invalid input.

✅ Enter the pathname of a Windows executable file. An executable file ordinarily ends with the .exe suffix. For example: C:\Program Files\Custom Utilities\StringFinder.exe

 

 

📌 간결하게 적어라

Be concise

 

소프트웨어 엔지니어들은 코드 라인 수를 최소화하고자 노력하곤 합니다. 짧은 코드일 수록 읽고 유지하는 것이 긴 코드 보다 용이하기 때문입니다. 문서와 Technical Writing 도 동일합니다. 문장을 간결하게 만드는 것은 굉장히 유용합니다.

 

- 간결한 문서는 빠르게 읽힌다.

- 간결한 문서는 유지하기 용이하다.

- 덧대어진 문서 라인은 추가적인 실패 지점을 야기할 수 있다.

 

(마지막 내용은 Extra lines of documentation introduce additional points of failure 을 의역했습니다)

 

가장 간결화 시킨 문서 구현하는데 시간이 걸리겠지만 분명히 가치가 있습니다. 간결한 문장은 긴 문장보다 더 강력한 의사소통을 하며, 보통 간결한 문장은 긴 문장보다 이해하기 쉽습니다.

 

오류 메세지를 간결하게 적고, 무엇이 중요한지 강조하고, 불필요한 내용을 지우세요.

간결화하는 것은 분명히 더 나은 글을 생산하지만, 필요한 정보를 지우지 않게 주의하세요.

 

❌ SQL 데이터베이스에 연결을 유지할 수 없습니다. [문제 해결 방법 설명]

✅ SQL 데이터베이스에 연결할 수 없습니다. [문제 해결 방법 설명]

❌ The resource was not found and cannot be differentiated. What you selected doesn't exist in the cluster. [Explanation of how to find valid resources in the cluster.]

✅ Resource <name> isn't in cluster <name>. [Explanation of how to find valid resources in the cluster.]

 

 

📌 이중 부정을 피하라

Avoid double negatives

 

문자이나 구문에서 두 번 부정하는 이중 부정을 피하세요. 이중 부정은 사용자들에게 아래 두 내용으로 헷갈리도록 만듭니다.

- 두 번의 부정으로 긍정이 되는가?

- 단순한 개발자의 실수인가?

 

❌ 해당 신호는 절대 발생되지 않으면 안됩니다.

✅ 해당 신호가 반드시 발생되어야 합니다.

❌ The App Engine service account must have permissions on the image, except the Storage Object Viewer role, unless the Storage Object Admin role is available.

✅ The App Engine service account must have one of the following roles:
Storage Object Admin
Storage Object Creator

 

 

📌 대상 독자를 위해 작성하라

Write for the target audience

 

오류 메세지를 확인하는 사람의 지식 범위를 고려하세요. 가령 아래의 첫 번째 예시에서는 단어인 '서버', '클러스터', 'CPU', '클라이언트', '드랍'이 포함되어 일반 소비자에게는 도움이 되지 않습니다.

 

✔️ For expert:

서버 클러스터 CPU 사용량이 92%가 되어 해당 서버가 클라이언트의 요청을 드랍했습니다. 
5분 뒤에 다시 시도해주세요.

 

일반 소비자들은 아래와 같은 오류 메세지가 더욱 효과적입니다.

 

✔️ For common consumers

너무 많은 고객이 해당 서비스를 사용하고 있어서 구매를 성공적으로 완료하지 못했습니다. 
해당 상품은 장바구니에서 다시 확인할 수 있습니다. 5분 후에 다시 시도해주시길 바랍니다.

 

 

📌 동일한 단어로 통일하라

Use terminology consistently

 

지칭되는 단어를 동일하게 유지해서 사용하세요. 특정 단어로 무엇인가를 지칭했다면, 모든 오류 메세지에서 동일하게 표현하세요. 만약 각각의 오류 메세지에서 다른 이름으로 불린다면 사용자들은 동일한 것을 지칭하는지 깨닫지 못할 수 있습니다.

 

❌ 127.0.0.1:56의 클러스터에 연결할 수 없습니다. minikube가 실행중인지 확인하세요.

✅ 127.0.0.1:56의 minikube에 연결할 수 없습니다. minikube가 실행중인지 확인하세요.

 

 

가독성을 높이는 오류 메세지 형식

Format error messages to enhance readability

 

오류 메세지의 가독성을 높이는 팁을 몇가지 살펴보겠습니다.

 

 

1/ 상세 문서에 링크를 더해라

Link to more detailed documentation

 

더 자세한 내용을 확인할 수 있는 링크를 추가하세요.

✅ 해당 요청에 안전하지 않은 정보가 포함되어 있습니다. 안전성을 위해 <link> 내용을 확인해주세요.
✅ Post contains unsafe information. Learn more about safety at <link to documentation>.

 

 

2/ 점차적으로 보여주어라

Use progressive disclosure

  

✅ 
TextField을 사용 시 선행적인 과정에서 Material를 필요로 합니다.

...(더 보기)

material 디자인을 개념적으로 살펴보면 각 위젯이 material Sheet위에 출력됩니다.
Material 위젯을 사용하기 위해서는 Material 위젯을 직접 추가하거나 혹은 해당 material 자체를 포함하는 위젯을 설치하세요.

 

 

3/ 오류와 가까운 곳에 명시하라

Place error messages close to the error

 

✅
1: program figure_1;
2: Grade = integer;
 - - - - -^ Syntax Error

Use ':' instead of '=' when declaring a variable.

3: var
4. print("Hello")

 

 

4/ 폰트 색을 주의해서 사용하라

Handle font colors carefully

 

❌ The argument expects only digits. 
Therefore, the supplied value is only partially correct: <green>3728<red>LJ</red>947</green>

✅ The argument expects only digits. 
Therefore, the highlighted part of the supplied value is incorrect: 3728<red>LJ</red>947

 

 

❌ 3728LJ947 은 혼란을 줄 수 있습니다.

✅ 3728LJ947 와 같이 필요한 부분만 강조하세요.

 

 

 

올바른 어조를 설정하기

오류 메세지에서의 어조는 사용자가 해석하는데 중요한 영향을 끼칩니다.

 

1/ 긍정적인 어조 사용하라

Be positive

 

사용자에게 무엇이 잘못되었는지를 말하기 보다, 어떤 것이 올바른 지 전달하세요.

 

❌ 이름을 입력하지 않았습니다.

✅ 이름을 입력하세요.

❌ You entered an invalid postal code.

✅ Enter a valid postal code. [Explanation of valid postal code.]

 

 

2/ 과한 미안함을 갖지 마라

Don’t be overly apologetic

 

긍정적인 태도를 유지하면서 "죄송하지만" 혹은 "부디" 와 같은 단어는 지양하세요. 대신 문제점과 해결점을 명백히 적으세요.

 

❌ 죄송하지만, 일시적인 서버 오류로 Spreadsheet를 불러오지 못했습니다. 불편을 끼쳐 드려 죄송합니다. 
잠시 뒤에 다시 시도해주시길 바랍니다.

✅ Google Docs가 일시적인 시간동안 Spreadsheet를 열지 못합니다. 
그 동안 문서 목록에서 Spreadsheet를 마우스 오른쪽 클릭으로 다운로드하십시오.

 

 

3/ 유머를 지양하라

Avoid humor

 

오류 메세지에 유머를 넣으려고 하지 마세요. 유머는 다음과 같은 이유로 지양합니다.

 

- 오류는 사용자를 혼란하게 만들며, 화난 사용자는 일반적으로 유머를 받아들이지 않는다.

- 사용자는 유머를 오해할 수도 있다. (농담이 항상 잘 통하는 것은 아니다)

- 유머는 오류 메세지의 본질을 없앤다.

 

❌ 지금 서버가 실행안되는 것 같죠? 한 번 잡으러 가봅시다 :D

✅ 서버가 일시적으로 사용 불가 상태입니다. 잠시 후 다시 시도해주세요.

 

 

4/ 사용자를 비난하지 마라

Don’t blame the user

 

가능하다면, 오류 메세지 내용이 비난하는 내용보다 잘못된 점에 초점을 맞도록 작성하세요.

 

❌ 당신은 오프라인 상태의 프린터를 입력했습니다.

✅ 당신의 프린터가 오프라인 상태입니다.