개발자를 위한 글쓰기 가이드 - 유영경

메일 작성

받는 사람을 명확하게 지정한다

받는 사람
메일 내용을 반드시 알아야 할 사람, 메일을 받고 업무를 진행해야 하는 사람

참조
메일 내용을 알아두면 좋은 사람, 지금 바로 일을 해야 하는 것은 아니지만 관련 있는 조직 담당자 등을 지정한다.

숨은 참조
메일 내용을 알아 두면 좋지만, '받는 사람'이나 '참조'에 있는 사람에게 굳이 존재를 알리거나 메일 주소를 알릴 필요가 없을 때 사용한다.

회의록 작성 원칙을 기억한다

미리 회의 안건을 공유한다.
특히 의사 결정을 해야 하는 안건이 있다면 참석자 각작의 의견을 정리해 올 수 있게 필요한 데이터를 전달한다.

안건별로 담당자와 일정을 정한다.
후속 회의를 줄이려면 해야 할 일을 명확하게 정해야 한다.

회의록에는 요점만 정리한다.
각 안건을 어떻게 결정했는지와 토론 사항을 요약해야 한다.

오류와 확인 메시지 작성

오류 메시지에 중요한 것을 해결 방법

오류 메시지
확인 메시지와 달리 오류 메시지는 작업을 완료할 수 없는 문제를 설명하기 위해 표시하는 텍스트이다.

좋은 오류 메시지 작성하기

오류 메시지 3요소: 상태, 원인, 해결 방법

• 상태: 사용자 관점에서 문제가 발생한 상태를 설명하는 것
• 원인: 문제가 발생한 이유
• 해결 방법: 문제를 어떻게 해결해야 하는지 알기 쉽게 설명한다.

좋은 오류 메시지 예시(1)

저장 공간이 부족하여 <- 원인
파일을 업로드하지 못했습니다. <- 상태
저장 공간을 확보한 후 다시 시도해 주세요. <- 해결 방법

좋은 오류 메시지 예시(2)

저장 공간이 부족하여 <- 원인
파일을 업로드하지 못했습니다. <- 상태
사용하지 않는 파일을 삭제하고 <- 해결 방법
다시 시도해 주세요.

직관적인 버튼 텍스트를 만든다.

휴지통 비우기
휴지통에 있는 모든 항목이 완전히 삭제됩니다.
[취소][확인]

위와 같이 작성해도 되지만 조금 더 직관적인 방법을 생각해 본다면, 버튼을 보고 다음 동작을 바로 알 수 있게 바꾸면 좋다.

휴지통 비우기
휴지통에 있는 모든 항목이 완전히 삭제됩니다.
[취소][휴지통 비우기]

장애 공지문의 기본 요소

• 장애 발생 시각과 지속 시간: 장애가 언제 발생했고 얼마나 지속됐는지를 알린다.
• 장애 발생 원인: 장애가 발생한 주요 원인을 적는다.
• 사용자 불편에 공감: 장애로 사용자가 입은 손해와 불편에 진심으로 공감한다.

사용자 가이드 작성

사용자에게 맞는 가이드 종류를 선택한다

사용자 가이드에 있어야 할 항목

• 사용자가 제품을 사용해 할 수 있는 일
• 제품을 사용하기 위해 알아야 할 사전 지식이나 참고 사항
• 업무별 사용 방법
• 실제 사용 예와 샘플 코드
• 추가 내용을 학습할 수 있는 참고 사이트
• 내용을 효율적으로 전달할 수 있는 스크린숏, 다이어그램, 차트 등

개념과 목적을 설명하는 개요를 추가한다

문서 개요에 있어야 할 항목

• 문서 정의
• 문서 목표
• 문서 독자
• 문서 변경 이력
• 문서에서 사용한 특정 스타일 소개
• 문서 내용 관련 문의처
• 문서 저작권