Technical Writing 4단계로 기술문서 작성하기

테크니컬 라이팅에서 쓰이는 테크니컬 라이팅 4대 원칙에 대해서 작성해보려고 합니다.  처음 테크니컬 라이팅 교육을 수강했을 때 가장 먼저 나오는 내용입니다. 반드시 이 원칙을 따라야 할 필요는 없지만 기술문서를 처음 작성해 보는 사람이라면 이 원칙에 따라 작성하는 것이 좋습니다. 

테크니컬 라이팅의 4원칙 정확성(Accuracy), 명확성(Clarity), 간결성(Concisenness), 일관성(Consistency)

---

1. 정확성(Accuracy)

테크니컬 라이팅의 첫 번째 원칙은 정확성입니다. 정확성이란 특정 독자가 필요로 하는 내용에 대하여 기술적 오류 없이 정확한 정보를 제공하는 것입니다. 잘못된 정보가 포함된 기술문서면 독자가 처음부터 끝까지 그 문서를 이해한다고 해도 필요 없는 정보를 제공했기 때문에 필요 없는 문서가 되기 때문입니다. 

정확성 있는 문서를 작성하기 위해서는 작성하는 주제에 대한 충분한 이해가 필요합니다. 특히 작성 후 담당자와의 리뷰를 통해 정확성을 높이는 것이 중요하며 변경이 자주 발생되는 문서는 문서 버전 관리 또한 중요합니다. 

아마 기술 문서를 작성하면서 내용 전체의 오류가 발생하는 것보다는 다음과 같은 오류들이 많이 발생할 것이라고 생각합니다. 

• 표 또는 문장에 정확한 단위를 사용하지 않음
• 주어가 명확하지 않음 
• UI화면에 표시된 버튼과 글에 설명된 버튼 이름이 다름
• 업데이트 내용이 반영되지 않음 

정확성을 높이기 위해서는 문서 작성 후 내용을 검증해보는 과정이 가장 중요합니다. 

 

2. 명확성(Clarity)

테크니컬 라이팅의 두 번째 원칙은 명확성입니다. 명확성이란 특정 독자가 문서를 읽었을 때 내용의 모호함 없이 한 번에 이해하도록 정보를 제공하는 것입니다. 어떤 문장을 읽을 때 내용이 이해가지 않아 몇 번씩 문장을 다시 읽는다는 것은 명확성이 떨어진 문장이라는 것입니다. 

이미 문서의 내용을 어느 정도 숙지하고 있는 독자라면 명확성이 떨어진 문서를 이해하는데 크게 무리가 없을 수도 있지만 처음 접해보는 독자는 내용을 이해하는 것이 어렵습니다. 특히 기술을 잘 이해하고 있는 엔지니어가 문서를 작성할 때 명확성이 떨어지는 경우가 있습니다. 이미 엔지니어가 잘 알고 있는 내용이기 때문에 내용을 누락하는 경우가 있기 때문입니다. 초보자 또는 외부 고객이 읽어도 문제가 없도록 작성해야 되기 때문에 모든 단계를 누락하지 않고 작성하는 것이 중요합니다. 

• 능동태와 수동태를 적절하게 사용 : 사용자가 동작을 수행하는 것이라면 명확하게 표현해줘야 합니다.
  (X) 시스템 대기모드 버튼을 클릭하면 화면을 잠급니다.
  (O) 시스템 대기모드 버튼을 클릭하면 화면이 잠깁니다. 

• 문맥에 맞는 조사를 사용
• 형용사와 부사를 지나치게 사용하지 않음
• 한 문장에는 하나의 주제만 작성 
• 사용자 관점에서 전문 용어 사용을 자제
• '/'를 사용하기보다는 '또는', '그리고'로 정확하게 명시
• 구체적으로 내용을 작성
• 모호한 표한 사용하지 않음 : 아마도, 원활하게 등처럼 모호한 표현은 사용하지 않습니다. 

 

3. 간결성(Conciseness)

테크니컬 라이팅 세 번째 원칙은 간결성입니다. 간결성이란 특정 독자가 정보를 빠르게 이해하도록 미사여구를 사용하지 않고 쉽고 간결한 쉬운 단어를 사용하는 것입니다. 기술 문서라고 해서 전문용어를 과도하게 사용하고 복잡하게 작성하는 것은 바람직하지 않습니다. 짧고 간결한 문장을 사용할수록 독자는 이해하기 쉽기 때문입니다. 

만약 지나치게 길게 작성된 문장이 있다면 한 문장의 하나의 주제만 들어가도록 수정하고 간결한 용어를 사용하면 가독성을 높일 수 있습니다. 

• 불필요한 단어 사용을 하지 않음
• 불필요한 수식어를 사용하지 않음 
• 부정문을 사용하기보다는 긍정적인 표현 사용

 

4. 일관성(Consistency)

테크니컬 라이팅 네 번째 원칙은 일관성입니다. 일관성이란 특정 독자가 문서를 읽었을 때 쉽게 이해하도록 일관성 있는 용어와 포맷을 사용하는 것을 말합니다. 예를 들어 회사 내에서는 'A'라는 용어를 누구는 'A' 다른 누구는 'B'라고 부르는 경우가 종종 있습니다. 이럴 경우에도 두 표현을 혼용하는 것이 아니라 한 가지 용어를 정해서 통일성 있게 작성해야 합니다. 

단어뿐만 아니라 표현방식 또한 통일해 주는 것이 좋습니다. '~한다.'라고 할 것인지 또는 '~합니다.'라고 작성할 것인지 정하고 일관되게 문장을 작성합니다. 문서의 제목과 본문 폰트 크기 등도 일관성 있게 통일하면 가독성이 높아지니 이 부분도 신경 쓰면 문서 전체의 일관성이 높아집니다. 문서의 포맷과 관련된 내용은 스타일 가이드와 관련된 문서에서 자세하게 설명하겠습니다. 

• 일관된 용어와 표현을 사용한다.
  A 버튼을 클릭해 프로그램을 종료합니다.
  A 버튼을 눌러 프로그램을 종료합니다. 
  ↓
  A 버튼을 클릭해 프로그램을 종료합니다. (동일한 동작에 대해서 일관된 용어를 사용)

---

여기까지 테크니컬 라이팅 4원칙에 대해서 알아봤습니다. 기술문서를 처음 작성해 보시는 분들이라면 이 원칙에 맞게 내가 문서를 작성하고 있는지 검토해보시면 좋을 것 같습니다. 항상 위 원칙을 적용해서 작성하려고 하지만 용어를 사용하다 보면 다르게 사용하기도 하고 명확하게 표현이 되어있지 않은 경우도 많더라고요😥