Writing task-oriented information

항상 audience를 염두에 두고 있어야 함

다음 question을 고려해야 함

• Does each step represent an action the user takes?
• Are the results of an action clearly explained?
• Would a graphic help explain an action more clearly?

Elements of a procedure

task-oriented information

• steps requiring action by the user
• information about the results of those actions
• to clarify what the user does
  • graphics
  • tables
  • notes

Introducing the procedure

• 본격적으로 따라해야 할 step을 나열하기 전에 lead-in sentence or paragraph 써주기
• 만약에 lead-ins로 문장을 쓴다면, 다음 lead-ins도 같은 문법적인 패턴을 따라야 함
  • To print a file, follow these steps:
  • To delete a file, follow these steps: 🙆‍♀️
  • You can delete a file by completing the following steps: 🙅‍♀️

Breaking down a task into steps

• 하나의 스텝은 하나의 액션 혹은 (관련있는) 액션그룹을 포함함
• Group selecting a menu and a choice from that menu:
  • Select the Edit menu, then Copy.
  • Type ftp at the command prompt, then press Enter.

Don’t 🙅‍♀️

• 서로 다른 복수의 액션을 너무 무리해서(?) 그루핑하지 말기
• 특히 서로 다른 메뉴를 선택해야 하는 걸 하나의 스텝으로 포함하지 말것

Including the results

• 괜히 넘버링을 나눠서 헷갈리게 하지 말기
• use an element for a paragraph that’s permitted within a procedure
• result를 다음 줄로 넘기면 더 명확하게 구분할 수 있음

Select the Format menu, then Page Layout, then Master Page Usage.
The Master Page Usage dialog box is displayed.

Adding notes, warnings, and cautions

Note

• 언급은 돼야 하지만 a bit off-topic인 정보
• user한테 도움은 되지만 damage를 초래하진 않는 내용

Warnings

• damage를 주는 특정 액션 설명
• 예를 들면, 특정 버튼을 누르면 파일을 영구적으로 삭제하는 것

Cautions

• 발생가능한 위험이지만 사람에게 해를 가하진 않음

template-base로 일한다면 style guide에서 언제 note, caution, warning을 어떤 format으로 사용할지 가이드를 적어둘 수 있음

note를 너무 남발하면 중요한 정보가 눈에 안 들어오고, 집중도를 떨어뜨릴 수 있음

Using bulleted and numbered lists

• 리스트 아이템이 3개 이상이면 bullet을 쓰기
• 특정한 순서대로 수행해야 하는 스텝일 때는 bullet이 아닌 numbered list 사용

Lettings illustrations tell the story

• step by step을 따라할 때 유저가 보게될 화면 스크린샷을 포함하는 게 제일 좋음
• 온라인 콘텐츠라면, step by step action 보여주는 데는 애니메이션이나 video clip이 더 효과적임
• graphic 넣는다면 figure caption에 purpose를 설명해야 함
• 사용자 수준을 고려해서 graphic을 넣을지 말기 결정함

Sunny 의견) but UI가 바뀌는 걸 반영을 안하면 안 넣는것만 못하다…

실제 화면이랑 문서 스크린샷 다르면 오히려 사용자 헷갈리게 하거나

문서 관리 안한다는 안 좋은 인상 줄 수 있음 😥

& 스크린샷 반영할 때 기준도 스타일 가이드에 있으면 좋겠음

예를 들어서 개인 정보 노출되지 않게 어떻게 가릴지?

(사전에 합의 안하면) 개인정보를 누군가는 모자이크 처리하고 누군 또 화이트 박스로 가리고 제각각..인 경우도 있음

Organizing information in tables

Links in online content

• 어떤 resource를 링크를 걸지 company policy가 있다면 이를 준수해야 함
• 링크 깨지지 않도록 follow-up 필요

출처: Technical Writing 101