기술문서 어떻게 작성해야 할까? 사용자 중심의 기술문서 작성하기

기술문서라고 하면 다양한 문서 유형의 문서들이 존재합니다. 하지만 다양한 문서 유형일지라도 '사용자(독자)'중심으로 작성해야 한다는 것입니다. 문서로 기록한다는 것은 비록 '나' 자신일지라도 독자는 반드시 존재하기 때문입니다.

기술문서를 처음 작성할 때 어려움이 따르지만 사용자(독자) 중심으로 글을 쓰고자 한다면 쉽게 방향을 잡을 수 있을 것입니다. 사용자(독자) 중심으로 어떻게 기술문서를 작성해야 하는지 정리해보고자 합니다.

 

기술문서를 작성하기 전 먼저 독자는 누구인지 독자의 수준은 어떤지 고려해야합니다. 일반 사용자 그리고 초보 개발자들을 위한 문서라면 문서에 사용된 용어 자체가 쉬운 용어로 작성되어야 합니다. 그리고 사용자가 반드시 필요로 하는 내용들만 기술하도록 해야합니다. 많은 정보를 제공하는 것도 좋지만 과도하게 많은 정보를 제공한다면 독자는 이 정보가 나에게 필요한 정보가 맞는지 생각하고 시간을 허비하게 됩니다.

---

그럼 독자는 누구인지?는 어떻게 정할까

이 문서를 가장 많이 사용하는 사람은 누구인지를 생각하고 이 사람이 해당 기술에 대해 얼마나 알고 있는지를 파악해야 합니다. 요즘에는 기업에서 기술블로그 등도 많이 운영하고 있는데, 이 경우에도 기술블로그를 누구를 대상으로 작성하고 있는지 생각해야 합니다. 기술블로그를 보는 사람들은 어느정도 해당 회사에 대한 정보를 알고 있거나 그 업계에 종사하는 사람들이 많을 것이기 때문에 그 사람들의 수준을 고려해서 작성해야 합니다. 타 회사들의 기술 블로그를 읽으면서 누구를 대상으로 하고 있는지 어떤 수준으로 작성하고 있는지 참고하는 것도 좋습니다. 

제품을 판매할 때 매뉴얼을 제공하는 경우에는 영업 부서나 CS부서에게 독자의 수준 정도를 파악할 수도 있습니다. B2B대상인지 B2C대상인지에 따라서도 독자 수준이 달라질 수 있습니다. 만약 반도체 장비 매뉴얼을 반도체 장비를 구매하는 삼성 또는 하이닉스 사에 전달한다고 한다면 독자는 어느정도 반도체 장비에 대한 이해가 있기 때문에 업계에서 자주 사용되는 용어들은 이미 알고 있을 확률이 높습니다. 

웹 서비스를 제공할 때에도 '자주 묻는 질문' 등을 따로 작성해 두는 경우가 대부분입니다. 이런 것도 고객에게 접점이 있는 부서인 CS부서에게 자료를 요청해서 어떤 질문들이 자주 나오는지 파악하고 질문에 대한 답변을 하나의 게시글로 작성해 두는 것입니다. 

---

독자가 누구인지 설정했다면 목적도 고려해야 한다.

기술문서를 가지고 독자가 언제 어떻게 활용하는가를 생각하고 작성해야합니다. 제품을 소개하는 것에 초점을 맞춘 문서인지 아니면 제품을 사용하는데에 초점을 맞춘 문서인지 등을 고려해서 작성해야한다는 것입니다. 

절차서를 작성한다면 누가/언제/왜/어떻게 동작을 수행하는지에 대해 초점을 맞춰서 작성해야합니다. 절차를 진행하면서 고려해야할 사항은 있는지 그리고 선행되어야할 동작이 있는지 등을 고려해서 작성합니다. 절차서이기 때문에 앞에 숫자를 붙여서 작성이 될텐데 해당 번호에 하나의 동작만 작성해서 사용자가 한번에 한 동작만 수행할 수 있도록 합니다.
여러가지의 동작이 한 문장안에 작성되어있으면 동시에 그 동작을 수행할 수도 있고 또는 문장이 너무 길어져서 여러번 그 문서를 읽어야 될지도 모릅니다. 

예시)
1.4 △△시뮬레이터로  그래프그리기 → '~하기'와 같이 동작을 작성해주면 사용자가 목차만 보고도 바로 찾을 수 있다. 
△△시뮬레이터는 프로그램 실행 전 oo을 확인할 때 사용합니다. ~→ 이 동작을 언제/왜 수행하는지 작성한다. 
 1. PC 바탕화면에 있는 'X'버튼을 클릭해 시뮬레이터를 실행합니다. 
 2. 화면 우측에 있는 'Y'버튼을 클릭해 ~메뉴로 들어갑니다. → 독자가 실제로 수행하는 동작 순서대로 내용을 작성한다. 

독자가 실제로 수행하는 동작 순서대로 작성 시에 가끔 이렇게 작성되어 있는 문서들도 있습니다.

(X)

1. 프로그램의 Main화면에서 'A'버튼을 클릭합니다.
2. 팝업창이 나타납니다. 

(O)

1. 프로그램의 Main화면에서 'A'버튼을 클릭하면 팝업창이 나타납니다. 

위 예시의 차이는 무엇일까? '2. 팝업창이 나타납니다'는 사용자가 실제 수행하는 동작이 아니고 클릭하면 프로그램이 수행하는 동작이기 때문에 굳이 번호를 하나 더 붙여서 작성해줄 필요는 없습니다. 클릭을 하면 팝업창이 나타나기 때문이입니다. 

물론 하나의 간단한 예시이기 때문에 실제로 작성할 때는 항상 예외는 있는 법입니다. 다만 사용자가 실제 수행하는 동작 중심으로 작성한다면 작성하기가 훨씬 수월할 것입니다. 

만약, 제품의 프로세스를 설명하는 문서라면 플로우 차트 등을 삽입하고 그에 대한 설명을 작성하는 등 어떤 문서냐에 따라 작성 시 고려해야할 사항과 작성하는 방법이 조금씩 달라집니다. 

---

작성자는 테크니컬 라이팅 4원칙(정확성,명확성,간결성,일관성)에 맞게 문서를 작성해야 한다. 

읽는 사람을 고려해 내용 뿐만 아니라 문서의 형식을 통일해 가독성을 높여야 합니다. 아무리 좋은 정보라고 해도 줄글 형태로 나열한다면 가독성이 떨어지기 때문입니다. 

테크니컬라이팅의 4원칙에 대한 자세한 내용은 아래 포스팅에 따로 작성해두었습니다. 

https://jidocument.tistory.com/entry/Technical-Writing-4%EB%8B%A8%EA%B3%84%EB%A1%9C-%EA%B8%B0%EC%88%A0%EB%AC%B8%EC%84%9C-%EC%9E%91%EC%84%B1%ED%95%98%EA%B8%B0?category=1046524 

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

회사에서 사용하는 스타일 가이드가 있다면 그에 따르는 것이 가장 편리하겠지만 몇가지 정리해 본다면

• 목차는 3수준 까지만 작성하도록 하는 것이 좋습니다. 
• 그림이나 표를 삽입할 경우에는 캡션을 명시하거나 그림과 표에 대한 설명을 작성합니다. 그림과 표는 글을 대체하는 것이 아니라 보완해주는 개념입니다. 그림에서 표현할 수 있는 정보는 한정적이기 때문에 글을 작성해서 설명해줘야 합니다. 
• 용어를 통일합니다. 처음 사용되는 용어를 사용한다면 용어에 대한 설명을 작성해줍니다. 

MS Word를 사용해 문서를 가독성 있고 보기 좋게 만드는 방법은 따로 포스팅을 하고 템플릿도 배포해보려고 노력중입니다.(언제 작성할지😭😭)

 

---

기술문서를 처음 작성할 때는 어떻게 작성해야될지 막막하지만 위 내용들을 생각하고 작성하다 보면 방향을 잡고 빠르게 작성할 수 있습니다. 결국 문서를 작성한다는 것은 독자를 고려해서 작성해야 한다는 점! 독자가 누구인지 독자의 수준은 어떤지 이해만 해도 어떻게 작성해야 할지 감이 잡힙니다. 하지만 저도 여전히 새롭고 여전히 어려운거 같습니다..:)