Self-editing

Adopt a style guide

회사나 조직 또는 큰 오픈소스 커뮤니티는 자체 스타일 가이드를 가지고 있거나 이미 존재하는 스타일 가이드를 도입합니다. 한번도 스타일 가이드를 따르려해본 적이 없다면 구글 스타일 가이드를 참고해보세요. style-guide highlights(highlights) 를 도입하는 것으로 시작해도 좋습니다.

작은 팀 단위 문서나 작은 오픈소스 프로젝트에서는 highlights 로도 충분할 것입니다.

highlights 는 Technical Writing One 에서 배웠던 것 외에도 유용한 기술을 소개합니다:

• 2인칭 대명사를 사용하세요. 우리 가 아닌 당신 을 사용하여 독자를 지칭하세요.
• 지시문 뒤가 아닌 앞에 조건 을 명시하세요.
• 코드 관련 내용은 코드를 위한 폰트로 표현하세요.

Think like your audience

독자가 누구인지 파악하고, 그들의 시점에서 문서를 바라보세요. 문서가 그들의 입장에서 필요로 하고 있는 것을 충분히 설명하고 있는지, 목적이 분명한지 확실히 하세요.

독자의 페르소나를 그려보는 것도 도움이 된세요. 페르소나에는 아래와 같은 항목들이 포함될 수 있습니다:

• 시스템 엔지니어, QA 테스터 등의 역할.
• 데이터베이스 복구 와 같은 목적.
• 독자의 지식과 경험에 대한 몇가지 가정. 예를 들어:
  • 파이썬에 익숙하다.
  • os로는 리눅스를 사용한다.
  • cli 환경을 다루는 데에 익숙하다.

또한 특정 주제에 대해 독자들이 더 알수 있도록 링크를 제공하는 것 역시 유용합니다.

Technical Writing One 세션의 Audience 섹션을 참조하세요

Read it out loud

맥락에 따라, 사용된 문체가 독자를 지루하게 만들거나 또는 더 끌어들이는 힘을 가질 수 있습니다. 예를 들어, 오픈소스 참여자를 모집하기 위한 글에는 비격식적이고 구어체 문체를 사용할 수 있지만 B2B 애플리케이션의 개발자 가이드는 더 격식있는 문체를 사용하곤 합니다.

만약 문체가 충분히 구어체를 사용하고 있는지 확인하기 위해서는 직접 소리내어 읽어보세요. 어색한 표현이 있는지, 너무 긴 문장이나 부자연스러운 내용이 있는지 살펴보세요. 스크린 리더를 사용해도 좋습니다.

관련하여 Style and authorial tone 에서 도움을 받을 수 있습니다.

'입말' 이라는 표현도 존재합니다.

Come back to it later

한번 초안을 작성하고 나서, 한시간 뒤에 다시 검토해보세요. 거의 항상 개선의 여지가 발견될 것입니다.

Find a peer editor

엔지니어가 코드리뷰를 하듯, 문서를 작성할 때에도 문서에 피드백을 줄 동료가 필요합니다. 문서에 피드백을 줄 동료는 문서가 설명하는 대상의 전문가일 필요는 없지만, 사용하고 있는 스타일 가이드에 대한 이해는 필요로 합니다.