기술문서 작성 완벽 가이드

 기술 문서를 작성을 고민하던 중 끌리는 제목의 책을 골랐다. 처음에는 단지 그 뿐이었다. 책을 보고 내가 하는 작업이 테크니컬 라이터라는 직업으로써 다른 회사에 존재하고 있다는 것이 흥미로웠다.

11명의 테크니컬 라이터에게 질문한 내용들이 포함되어 있다.

 

 가끔 어떤 기술 문서는 왜 이렇게 돌아가는지 작동 원리가 나와있지 않거나, 내가 해결하고 싶은 문제를 장황하게 설명하여 지치게 만든다. 작동 원리가 나와있지 않은 문서는 테스트 코드를 작성하기 쉽지 않고, 응용하기 어렵다. 이 책의 저자 또한 만족할 만한 문서를 찾다가 작성했다는 점에서 공감이 됐다. 게다가 한 명의 저자가 아닌 리눅스 재단, 구글, 스트라이프, 론치다클리, 영국 정부와 같은 곳에서 개발자를 위한 문서작성을 하는 저자들이 함께 작성했기에 더욱 신뢰가 갔다. 

 개발자들은 쿠버네티스의 모든 부분이 어떻게 짜맞춰지는지 알고 싶었지만, 도움이 되는 콘텐츠가 없었습니다. 저는 개발자가 필요한 정보를 약5분 내에 찾지 못하면 프로젝트를 포기하고 다른 프로젝트를 찾아 떠날 수 있음을 곧 알게 되었습니다. 그것이 제가 현재 깃헙에서 27,000개 이상의 스타를 받은 실습 접근 방식인 Kubernetes the Hard Way를 작성하게 된 이유입니다. 마찬가지로, 개발자들이 인프라 운영을 위해 쿠버네티스를 빠르게 시작하고 실행하는 방법에 대한 정보를 찾고 있을 때 저는 공동 저자와 함께 적절한 제목을 붙인 책 쿠버네티스 시작하기(Kubernetes: Up and Running)를 썻습니다.

- 기술 문서 작성 가이드

 

 

 

 

 이 책은 하버드 대학의 한 경제학자 그룹의 연구로 시작한다. 그 연구의 목적은 사람들이 다른 사람도 자신과 같은 지식을 갖고 있다고 가정한다는 것이다. 그들은 이 인지력 편향을 "지식의 저주(curse of knowledge)"라 명명했다. 예시로, 커뮤니케이션이 익숙하지 않은 동료가 지식에 저주에 걸려 내가 모르는 전문 용어를 사용하거나, "이 정도는 알겠지?"라며 자세히 설명을 안해주는 경우를 들 수 있다.

 

 사용자를 위한 문서를 작성하려면, 지식의 저주를 극복하고, 그들이 누구인지, 무엇을 달성하고 싶은지 파악하는게 중요하다.

 

 

 

 

 기술 문서의 콘텐츠 유형은 크게 6가지가 있다. 코드 주석, README, 시작하기 문서, 개념문서, 절차문서, 참조문서다. 코드의 주석과 README는 기술 문서를 작성하지 않는 개발자도 많이 사용하는 문서다. 코드베이스가 커질 수록 과거에 내린 결정의 맥락을 파악하기 위해 사용한다. 절차 문서는 튜토리얼과 How-to 문서로 나눠진다. How-to 문서는 사용자가 실제 코드를 사용하는 실례에 기반을 둔다. 참조 문서는 API 레퍼런스, 용어집, 문제 해결 문서, 변경 로그가 있다. 이 처럼 문서를 구성하는 콘텐츠의 유형이 정해져 있고, 실제 기술 문서의 구성 또한 유사한 형식으로 만들어져 있다는 것을 알 수 있다. "기술문서 작성 가이드"에 나와있는 콘텐츠 유형이 어떤 독자를 목표로 만들어졌는지 안다면 원하는 정보를 찾는데 도움이 될것이다.

 

• 쿠버네티스 기술 문서

쿠버네티스란 무엇인가?

 

 

 

• 스프링 부트 기술 문서

Spring Boot :: Spring Boot

 

• 그레이들 기술 문서

Gradle User Manual

 

 

 

 

 

 문서 작성을 시작하기 위해서는 먼저 문서의 제목을 적절하게 설정해야 한다. 콘텐츠 구조화를 쉽게 할 뿐 아니라 검색 엔진 최적화(SEO)에도 중요하다. 이후 전체적인 문서의 일관성을 생각해보자. 제목, 단락, 절차, 목록, 안내 문구 (주의, 경고, 참고)를 구분하고, 주의일 경우 어떻게 표현할지 경고일경우 어떻게 표현할지 일관성있게 구성하자. 문서의 내용이 적절한지 검토하는 방법과 피드백을 받는 방법도 구체적으로 나와있다.

1. 문서 제목이 짧고 구체적이다.
2. 섹션 제목이 논리적인 순서로 배치되고 일관성이 있다.
3. 문서의 목적이 첫 번째 단락에 설명되어 있다.
4. 절차가 테스트되었고 잘 작동한다.
5. 기술적 개념에 대한 설명이나 해당하는 링크를 제공한다.
6. 문서가 템플릿의 구조를 따른다.
7. 모든 링크가 작동한다.
8. 맞춤법 및 문법 검사기를 실행했다.
9. 그래픽과 이미지가 명확하고 유용하다.
10. 모든 필수 조건과 다음 단계가 명시되어있다.

 

 

 

 

 기술문서 샘플코드의 목적은 코드를 복사 & 붙여넣기하여 독자의 시간을 절약할 수 있다는 것이다. 하지만, 코드를 실제로 적용하려면 일부 데이터를 교체해야 할 수도 있으므로, 독자가 샘플 데이터를 언제 교체해야 하는지, 어떤 값으로 교체해야 하는지를 모두 작성해 두어야 한다. 기술 문서의 샘플코드가 필요한 이유를 이해하고 문서를 작성하자. 어떤 방법으로 독자의 시간을 더 줄여줄 수 있는지 생각해보자. 나아가서 기술 문서의 유지 관리를 자동화하여 작성하는 시간을 절약할 수 있도록 하자. 문서에 마지막 수정 날짜를 표시하기, 404 오류가 나는지 확인하기, 맞춤법 검사기 등이 있다.

 

 

 

 

 문서의 품질 관련된 내용도 나오는데, 테크니컬 라이터는 KPI를 어떻게 측정하는지 생각해 볼 수 있었다. 기술 문서들이 어떤 원리로 품질이 측정됐고 배포됐는지 생각해봤다. 근데, 일부 측정 항목은 영문 기준이라 한국어 기술 문서에 적용할 수 있을 지 의문이다. 품질 측정중 한 분야로 간결성이 있는데 문장은 고등학생 수준으로 작성하라고 되어있다. 영문은 문장의 난이도를 측정하는 연구가 이미 많이있었기 때문에 오픈소스를 통해 문장의 전체 수준을 책정할 수 있는 기술이 있다고 한다. 한글 문서에 사용할 수 있는 분야를 선택하는게 필요하지 않을까 싶다.

 문서 품질을 측정하기 전에 먼저 "품질"을 정의해야 합니다. 다행히도 구글의 문서 작성자와 엔지니어들로 구성된 연구 그룹이 시간을 들여 이 질문을 놓고 고민했습니다. 그들은 코드 품질을 평가하는 것과 유사한 방법으로 문서 품질을 평가했습니다. 그들이 만든 문서 품질에 대한 정의는 매우 간단합니다. "목적을 달성하는 문서가 좋은 문서다."