구글에서 제안하는 최적화된 오류 메세지 작성법

원문 Writing Helpful Error Messages
이외에도 공학자들을 위한 techincal 능력 향상을 위해 공식 사이트 에서 교육자료를 공유하고 있다.

자세한 가이드를 하나씩 살펴보기 전,
오류메세지 작성 시 규칙을 먼저 알아보도록 하자.

1. 오류 알림을 즉시 발생시켜라.
2. 실패를 조용하게 넘기지 마라.
3. 오류의 근원이 묻히지 않도록 해라.
4. 오류 코드를 기록하라.

최적화된 오류 메세지

1. 오류의 원인을 전달하라 identify the error's cause
   사용자에게 어떤 문제가 있는 지 확실하게 전달해야 한다.

	✖ 잘못된 접근입니다.
 
	✔ 해당 디렉토리가 존재하지만 쓰기 가능한 상태가 아닙니다. 
    해당 디렉토리에 파일을 추가하려면, 디렉토리가 쓰기 가능한 상태여야 합니다.
    [쓰기 가능한 상태로 만들 수 있는 방법에 대한 설명~]

2. 잘못된 입력 값을 전달하라 identify the user's invalid inputs
   오류 메세지에 문제가 되는 값의 이유를 명시하여 사용자가 문제가 되는 부분을 알게 해야 한다.
   만약, 오류 메세지가 여러 개여서 한 줄에 명시 할 수 없다면?
   - 문제점들을 점차적인 방식으로 명시하고 버튼을 제공해서 유저의 클릭으로 리스트된 오류를 보여주도록 하자
   - 문제가 되는 입력 값을 모두 제거하고, 필요가 되는 부분만을 남기자.

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

3. 요구사항과 제약사항을 명시하라 Specify Requirements and Constraints
   오류가 발생한 이유를 이해할 수 있도록..

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

4. 문제 해결 방안을 설명하라 Explain how to fix the problem

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

5. 예시를 제공하라 Provide Example

	✖ 유효하지 않은 이메일 주소
 
	✔ 입력한 이메일 주소(dksjdksn)에 @ 표시와 도메인 이름이 누락되었습니다.
    올바른 예시: dksjdksn@example.com

6. 간결하게 적어라 Be concise
   코드와 문서, Technical Writing 또한 동일하다. 간결하게 만드는 것은 어디에서나 유용하다.
   - 간결한 문서는 빠르게 읽힌다.
   - 간결한 문서는 유지하기에 용이하다.
   - 덧대어진 문서 라인은 추가적인 실패 지점을 야기할 수 있다.
   오류 메세지를 간결하게 적고, 무엇이 중요한지 강조하고, 불필요한 내용을 지워라.
   간결화하는 것은 분명히 더 나은 글을 생산하지만, 필요한 정보를 지우지 않게 주의하라.
   

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

7. 이중 부정을 피하라 Avoid double negatives
   이중 부정은 1) 두번의 부정으로 긍정이 될 수 있는 문제를 야기하며 2) 단순한 개발자의 실수인가라는 의심 을 들게 한다.

	✖ 해당 신호는 절대 발생되지 않으면 안됩니다.
 
	✔ 해당 신호가 반드시 발생되어야 합니다.

8. 대상 독자를 위해 작성하라 Write for the target audience

9. 동일한 단어로 통일하라 Use terminology consistently

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

1. 상세 문서에 링크를 첨부해라

✅ 해당 요청에 안전하지 않은 정보가 포함되어 있습니다. 안전성을 위해 <link> 내용을 확인해주세요.

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

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

...(더 보기)

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

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

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

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

3: var
4. print("Hello")

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

올바른 어조를 설정하기

1. 긍정적인 어조 사용 Be positive

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

✅ 이름을 입력하세요.

2. 과한 미안함 금지
   '죄송하지만', '부디' 같은 단어는 지양하자. 대신 문제점과 해결점을 명백하게 작성하자.

❌ 죄송하지만, 일시적인 서버 오류로 Spreadsheet를 불러오지 못했습니다. 
불편을 끼쳐 드려 죄송합니다. 
죄송하고 죄송하고 구구절절... 잠시 후에 열어 드릴게요 ㅠ.ㅜ

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

3. 유머를 지양하라
   -. 오류는 사용자를 혼란하게 만들며, 화난 사용자🤬는 일반적으로 유머를 받아들이지 않는다.
   -. 사용자는 유머를 오해할 수 있다. (농담이 항상 잘 통하는 것은 아니다.)
   -. 유머는 오류 메세지의 본질을 없앤다.

❌ 서버가 실행되고 있을까요? 가서 잡아보세요 :D

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

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

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

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

---

메세지 하나하나에도 공을 들여야한다.