Technical Writing을 위해 지켜야할 원리원칙들

Technical Writing이란 기술서나 사양서 등의 기술적인 문장을 작성하는 것을 말합니다.
이러한 문장은 단순히 정보를 정리해두는 것 뿐만 아니라 전혀 관계없는 타인 혹은 후임자 등 다른 사람들에게도 명쾌하게 읽혀야한다는 점이 매우 중요한데요.
이를 위해 구글에서 공개한 교육용 자료인 ‘Technical Writing One, Two’에서 말하는 내용 중 핵심적인 원리원칙을 정리해보았습니다.

Technical Writing One

Technical Writing One에서는 각 문장이나 문맥에 있어 정보전달을 최적화하는데 중점을 둔 원칙들입니다.

• 용어는 문서내에서 일관성을 가져야한다.
• 애매한 대명사의 사용은 자제한다.
• 수동태보다는 능동태를 선호한다.
• 강한 동사를 선택한다.
• 애매한 동사보다 의미가 명확한 동사를 선택한다.
• 1문장에 1메세지
• 긴 문장은 리스트 형식으로 개편한다.
• 불필요한 말은 배제한다.
• 순서가 중요한 경우 번호를 붙인 리스트를 이용하고, 순서가 중요하지 않은 경우 기호를 붙인 리스트를 사용한다.
• 리스트를 사용할 경우 각각의 병렬성을 고려한다.
• 번호를 붙인 리스트는 명령어로 시작한다.
• 리스트와 표를 적절히 사용한다.
• 단락의 골자를 보여주는 좋은 머릿말을 작성한다.
• 1단락 1개의 주제로 짠다.
• 읽는 사람의 전제지식을 정의한다.
• 읽는 사람을 의식하여 작성한다.
• 문서의 첫 부분에 해당 문서의 주요 포인트를 명확하게 한다.

Technical Writing Two

Technical Writing Two는 문서의 목적달성을 최대한 이루어내기 위한 원리원칙입니다.

• 스타일가이드(템플릿)을 이용한다.
• 읽는 사람이 어떻게 생각할지를 고려한다.
• 작성한 문서를 소리내어 읽어본다.
• 초안을 작성하고 나중에 다시 읽어본다.
• 뛰어난 리뷰어를 발견한다.
• 문서의 아웃라인(개요)을 만들거나 혹은 자유롭게 작성한 후 정리한다.
• 문서의 범위 및 전제조건을 첫 부분에 표시한다.
• 될 수 있으면 작업 기반을 보여준다.
• 새로운 정보나 개념을 한 번에 다 보여주지 말고 조금씩 나눠서 보여준다.
• 일러스트를 그리기 전에 설명서를 작성한다.
• 1개의 지면내에 정보량을 제한한다.
• 캡션으로 중점을 설명하거나 화면에 주의를 뜻하는 마크를 추가하여 화면, 그림에 독자의 주의를 끈다.
• 이해하기 쉬운 단순한 샘플코드를 작성한다.
• 코드의 코멘트는 짧게 하지만 간결함보다는 명쾌함을 우선한다.
• 한 눈에 알 수 있는 코드에 코멘트는 작성하지 않는다.
• 코멘트는 코드 안에서 직관적이지 않은 부분을 보충하는 쪽으로 집중한다.
• 좋은 형태 뿐만이 아니라 나쁜 형태로 공유한다.
• 코드 샘플은 복수의 복잡성을 상정한 것으로 공유한다.
• 지속적으로 검토하는 것을 실천한다.
• 독자에 맞춰 각각 다른 자료형태를 제공한다.
• 독자가 이미 알고 있는 지식과 비교한다.
• 튜토리얼은 복수의 형태를 사용해 전달되기 쉽게 한다.
• 튜토리얼은 독자가 헷갈리기 쉬운 부분을 지적한다.

출처

https://developers.google.com/tech-writing/overview (구글 개발자 교육용 자료 - Technical Writing For Students) https://qiita.com/yasuoyasuo/items/c43783316a4d141a140f