728x90
원문 Writing Helpful Error Messages
이외에도 공학자들을 위한 techincal 능력 향상을 위해 공식 사이트 에서 교육자료를 공유하고 있다.
자세한 가이드를 하나씩 살펴보기 전,
오류메세지 작성 시 규칙을 먼저 알아보도록 하자.
- 오류 알림을 즉시 발생시켜라.
- 실패를 조용하게 넘기지 마라.
- 오류의 근원이 묻히지 않도록 해라.
- 오류 코드를 기록하라.
최적화된 오류 메세지
- 오류의 원인을 전달하라 identify the error's cause
사용자에게 어떤 문제가 있는 지 확실하게 전달해야 한다.
✖ 잘못된 접근입니다.
✔ 해당 디렉토리가 존재하지만 쓰기 가능한 상태가 아닙니다.
해당 디렉토리에 파일을 추가하려면, 디렉토리가 쓰기 가능한 상태여야 합니다.
[쓰기 가능한 상태로 만들 수 있는 방법에 대한 설명~]- 잘못된 입력 값을 전달하라 identify the user's invalid inputs
오류 메세지에 문제가 되는 값의 이유를 명시하여 사용자가 문제가 되는 부분을 알게 해야 한다.
만약, 오류 메세지가 여러 개여서 한 줄에 명시 할 수 없다면?
- 문제점들을 점차적인 방식으로 명시하고 버튼을 제공해서 유저의 클릭으로 리스트된 오류를 보여주도록 하자
- 문제가 되는 입력 값을 모두 제거하고, 필요가 되는 부분만을 남기자.
✖ 잘못된 우편 번호
✔ 한국의 우편 번호는 반드시 5자리의 숫자로 구성되어야 합니다.
입력된 우편번호(284619)는 6자리 숫자 입니다.- 요구사항과 제약사항을 명시하라 Specify Requirements and Constraints
오류가 발생한 이유를 이해할 수 있도록..
✖ 붙임 파일의 용량이 너무 큽니다.
✔ 붙임 파일의 용량(14MB)이 최대 허용 크기(10MB)를 초과했습니다.
[접근 가능한 방식에 대한 추가 설명...]- 문제 해결 방안을 설명하라 Explain how to fix the problem
✖ 해당 기기에서 X앱은 더 이상 지원하지 않습니다.
✔ 해당 기기에서 X앱은 더 이상 지원하지 않습니다.
X앱을 업데이트하려면, 앱 내의 '업데이트' 버튼을 클릭하세요- 예시를 제공하라 Provide Example
✖ 유효하지 않은 이메일 주소
✔ 입력한 이메일 주소(dksjdksn)에 @ 표시와 도메인 이름이 누락되었습니다.
올바른 예시: dksjdksn@example.com- 간결하게 적어라 Be concise
코드와 문서, Technical Writing 또한 동일하다. 간결하게 만드는 것은 어디에서나 유용하다.
- 간결한 문서는 빠르게 읽힌다.
- 간결한 문서는 유지하기에 용이하다.
- 덧대어진 문서 라인은 추가적인 실패 지점을 야기할 수 있다.
오류 메세지를 간결하게 적고, 무엇이 중요한지 강조하고, 불필요한 내용을 지워라.
간결화하는 것은 분명히 더 나은 글을 생산하지만, 필요한 정보를 지우지 않게 주의하라.
✖ SQL 데이터베이스에 연결을 유지할 수 없습니다 [문제 해결 방법 설명]
✔ SQL 데이터베이스에 연결할 수 없습니다. [문제 해결 방법 설명]- 이중 부정을 피하라 Avoid double negatives
이중 부정은 1) 두번의 부정으로 긍정이 될 수 있는 문제를 야기하며 2) 단순한 개발자의 실수인가라는 의심 을 들게 한다.
✖ 해당 신호는 절대 발생되지 않으면 안됩니다.
✔ 해당 신호가 반드시 발생되어야 합니다.- 대상 독자를 위해 작성하라 Write for the target audience
- 동일한 단어로 통일하라 Use terminology consistently
가독성을 높이는 오류 메세지 형식
- 상세 문서에 링크를 첨부해라
✅ 해당 요청에 안전하지 않은 정보가 포함되어 있습니다. 안전성을 위해 <link> 내용을 확인해주세요.- 점차적으로 보여주어라
✅
TextField을 사용 시 선행적인 과정에서 Material를 필요로 합니다.
...(더 보기)
material 디자인을 개념적으로 살펴보면 각 위젯이 material Sheet위에 출력됩니다.
Material 위젯을 사용하기 위해서는 Material 위젯을 직접 추가하거나
혹은 해당 material 자체를 포함하는 위젯을 설치하세요.- 오류와 가까운 곳에 명시하라
✅
1: program figure_1;
2: Grade = integer;
- - - - -^ Syntax Error
Use ':' instead of '=' when declaring a variable.
3: var
4. print("Hello")- 폰트 색을 주의해서 사용하라.
올바른 어조를 설정하기
- 긍정적인 어조 사용 Be positive
❌ 이름을 입력하지 않았습니다ㅡㅡ.
✅ 이름을 입력하세요.- 과한 미안함 금지
'죄송하지만', '부디' 같은 단어는 지양하자. 대신 문제점과 해결점을 명백하게 작성하자.
❌ 죄송하지만, 일시적인 서버 오류로 Spreadsheet를 불러오지 못했습니다.
불편을 끼쳐 드려 죄송합니다.
죄송하고 죄송하고 구구절절... 잠시 후에 열어 드릴게요 ㅠ.ㅜ
✅ Google Docs가 일시적인 시간동안 Spreadsheet를 열지 못합니다.
그 동안 문서 목록에서 Spreadsheet를 마우스 오른쪽 클릭으로 다운로드하십시오.- 유머를 지양하라
-. 오류는 사용자를 혼란하게 만들며, 화난 사용자🤬는 일반적으로 유머를 받아들이지 않는다.
-. 사용자는 유머를 오해할 수 있다. (농담이 항상 잘 통하는 것은 아니다.)
-. 유머는 오류 메세지의 본질을 없앤다.
❌ 서버가 실행되고 있을까요? 가서 잡아보세요 :D
✅ 서버가 일시적으로 사용 불가 상태입니다. 잠시 후 다시 시도해주세요.- 사용자를 비난하지 마라
❌ 당신은 오프라인 상태의 프린터를 입력했습니다.
✅ 당신의 프린터가 오프라인 상태입니다.메세지 하나하나에도 공을 들여야한다.
728x90
