기술문서(Technical Document)에는 어떤 문서들이 있을까?기술문서의 종류

지난번 " 기술문서(technical document)의 개념/중요성/범주는 무엇일까?"에서 기술문서의 범주와 예시에 대해서 간단하게 작성했다. 이번에는 대표적인 기술문서들에 대해서 보다 자세하게 작성해보고자 한다. 정말 다양한 문서들이 있겠지만 그중 대표적이고 가장 큰 범주들에 대해서 작성하고자 한다. 

---

API Guide/SDK Gudie

사실 나는 소프트웨어 쪽이 아니라 API가이드문서에 대해서 잘 알지 못한다😥 하지만 소프트웨어 테크니컬 라이터는 API가이드 문서 등을 작성하는 일이 많기 때문에 그래도 공부할겸 알아봤다. 

여기서 API가이드를 알려면 API가 뭔지를 알아야 하는데 간단하게 설명하자면

[응용프로그램에서 사용할 수 있도록 운영체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페이스 즉, API는 프로그램들이 서로 상호작용할 수 있도록 도와주는 역할을 한다. ]

라고 한다. 

그렇다면 API가이드는 무엇일까? API를 효과적으로 사용하고 통합하는 방법에 대한 지침이 포함된 기술 콘텐츠이다. API작업에 필요한 정보가 포함된 매뉴얼이라고 볼 수 있고 지원하는 함수나 클래스 등에 대한 세부정보가 적혀있다고 한다. 즉, 개발자를 위한 가이드 문서라고 볼 수 있겠다. 실제로 API가이드는 카카오나 네이버 등에서 제공을 하고 있어서 볼 수 있는 예시가 상당히 많다. 

https://developers.kakao.com/ 에 들어가면 API가이드를 확인할 수 있다, 실제로 카카오와 같은 IT계열사 채용공고를 보니 API가이드를 작성하는 업무를 맡는 테크니컬라이터 채용을 진행하는 비중이 많다. 아무래도 소프트웨어 쪽은 API가이드 작성이 중요하고 작성하기 위해서는 어느정도의 소프트웨어 지식과 코딩지식은 필수인듯 하다. 

Kakao Developers

 

---

Release Note(릴리즈 노트)

릴리즈 노트란 소프트웨어 또는 서비스가 업데이트 될 때마다 해당 서비스 배포와 함께 변경 사항, 기능 추가, 삭제, 버그 개선 등의 변경사항을 정리하여 정보를 제공하는 문서이다. 이 문서 또한 IT업계에서 주로 사용되는 문서이다. 

릴리즈 노트를 통해 사용자는 내가 사용하고 있던 서비스나 제품에 어떤 변경사항이 발생했는지 한 눈에 알 수 있다. 예를 들어 모바일 게임 같은 경우 발생하던 버그를 잡았다던지 등의 공지를 통해 사용자에게 업데이트 사항을 공유할 수 있다. 회사 내부적으로도 릴리즈 노트를 기록하면 누가 언제 어떻게 무엇을 업데이트 했는지 빠르게 확인할 수 있다. 

릴리즈 노트의 형식과 배포 방식은 회사마다 다양해서 정해진 규약은 없지만 그래도 기본 틀이 있으면 릴리즈 노트를 잘 작성할 수 있을 것이다. 릴리즈 노트를 중구난방으로 작성한다면 작성하는 의미가 없다. 너무 축약해서도 안되고 그렇다고 너무 길게 작성해서도 안된다. 릴리즈 노트가 무엇인지 찾아보다가 정리가 잘 되어 있는 글을 발견해서 링크를 걸어둔다. 해당 링크에서 릴리즈 노트의 구성요소와 작성 팁까지 자세하게 적혀있다. 

https://tech.kakaoenterprise.com/113?category=882489 

Release Note 톺아보기

 

---

User Guide/Manual(사용자 가이드/매뉴얼)

사용자 가이드와 매뉴얼은 가장 보편적으로 거론되는 기술문서이고 가장 많이 작성되고 있다. 제품이나 서비스가 고객에게 제공될 때 반드시 같이 나가는 문서이다. 처음 사용하는 독자를 고려해서 작성해야 되기 때문에 신경쓸 부분도 많고 매뉴얼을 전문적으로 만드는 업체도 따로 있을 정도이다. 업계에 따라 사용자 매뉴얼을 배포하는 방식 또한 다양하다.  

사용자 가이드/매뉴얼 문서는 많게는 몇백페이지까지 가는 경우도 많다. 이 때 사용자는 모든 문서를 처음부터 끝까지 절대로 다 읽지 않으므로(나 조차도 제품사고 사용설명서 잘 안읽는다^^) 문서를 구조화해서 사용자가 원하는 페이지를 빠르게 찾을 수 있도록 문서를 구조화하는 것이 중요하다. 목차 작성하는 방법 또한 나중에 작성할 예정이다. 

사용자 가이드/매뉴얼에서 요점만을 기록한 문서는 '퀵 스타트 가이드(Quick Start Guide'등도 제공될 수 있고 tutorials, how-to guides, installation & reference manuals, trouble shooting manuals, FAQ 등도 조금씩은 다르지만 비슷한 결을 가지고 있다고 볼 수 있다. (매뉴얼에 대한 자세한 내용은 다른 글에서 상세하게 적어볼 예정이다. 매뉴얼 작성도 많이 해보고 피드백도 많이 받아봤기 때문에 이참에 정리해보려고 한다.)

---

Application Note(어플리케이션 노트)

어플리케이션 노트의 독자는 주로 엔지니어이다. 어플리케이션 노트는 특정 기술 및 제품 사용 방법에 대해 작성한 자료이다. 설계 시 필요한 회로도나 코드 등의 정보가 들어갈 수 있다. 어떤 수식을 사용해서 어떤 코드를 사용해서 결과를 낼 수 있는지 등을 작성한 문서이다. 어플리케이션 노트는 회사에서 공개된 문서도 많으니 아래 예시를 보는게 보다 명확하게 이해가 될듯 싶다.

아래 링크는 애드몬드 옵틱의 어플리케이션 노트이다. 
https://www.edmundoptics.co.kr/knowledge-center/application-notes/

어플리케이션 노트 | 에드몬드 옵틱스

 

---

Whitepaper(화이트페이퍼)

화이트페이퍼는 외국에서는 보편적으로 사용되지만 우리나라에서는 아직까지 많이 사용되고 있지는 않다고 한다. 위키피디아에 검색했을 때 화이트페이퍼의 정의는 

[ 최근에는 정부뿐만 아니라 기업이나 연구소 등이 특정 주제에 대해서 연구 조사한 결과를 정리해 발표하는 문서에도 '백서'라는 표현을 사용하고 있어서 보다 넓은 의미의 종합적인 조사 보고서라는 의미를 갖게 되었다. ]

라고 나온다. 

종합적인 조사 보고서라고 하면 조금 애매한데 화이트 페이퍼는 특정한 제품이나 서비스 또는 기술에 대한 설명을 하거나 논리적이고 통계적인 문서라고 볼 수 있다. 화이트페이퍼를 배포해서 고객에게 회사가 가지고 있는 기술에 대해서 논리적으로 뒷받침하는 문서라고 볼 수 있다. 외국계회사 사이트를 들어가보면 웹에 화이트페이퍼가 게시되어있는 것을 종종 볼 수 있다. 화이트페이퍼는 영업 초기 단계에 기술을 소개할 때 많이 사용한다고 하니 마치 브로셔와 비슷하다고 생각은 들지만, 브로셔처럼 일러스트를 넣고 핵심만 간단히 작성하는 것이 아니라 보다 기술적인 문서이다.

또한 화이트페이퍼를 통해 제품의 시장이나 기술동향을 파악할 수 있다. 화이트 페이퍼와 어플리케이션 노트 예시는 아래 사이트를 참고하면 많은 자료를 볼 수 있다. 로옴사의 자료인데 포맷도 깔끔하고 정리도 잘 되어있어서 참고할만하다. 

https://www.rohm.co.kr/search/application-notes?Category=Application%20Note&DocType=Simulation%20Guide&SearchBox=application 

어플리케이션 노트와 디자인 모델 | 로옴 주식회사 - ROHM Semiconductor

 

---

위 문서들 뿐만 아니라 프로세스 문서(절차서, SOP)등 다양한 문서들이 기술문서에 속한다. 다음에도 다양한 유형의 기술문서들을 소개하고 각 문서들에 대해서 자세하게 작성하는 방법을 작성할 수 있도록 노력해보자🤗