[독서 기록] 기술문서 작성 완벽 가이드(자레드 바티 외 지음, 하성창 옮김, 한빛미디어)

 

 

 

하버드 대학의 한 경제학자 그룹은 사람들이 다른 사람도 자신과 같은 지식을 갖고 있다고 가정한다는 연구 결과를 내놓았습니다. 그들은 이 인지적 편향을 '지식의 저주'라고 명명했습니다.

- 30p 

 

지식의 저주를 기억하세요. 사용자는 여러분만큼 제품을 잘 알지 못하므로 제품과 관련하여 생각지도 못한 기초적인 질문을 할 수도 있습니다.

- 35p 

 

 

사용자 페르소나를 만들어 나갈 때는 사용자의 니즈를 고려해야 합니다. 누구에게 가장 도움이 필요한가요? 여러분의 소프트웨어를 사용하려고 할 때 누가 가장 가파른 학습 곡선을 경험하게 될까요? 

- 44p 

 

 

사용자 스토리는 일반적으로 다음과 같은 형식을 따릅니다. '[사용자 유형]으로서, [목표]를 할 수 있도록 [행동]을 하고 싶다.'

- 44p

 

 

개발자에게 가장 기본적인 콘텐츠 유형은 코드 주석입니다. 코드 주석은 자신이 작성한 코드가 무엇을 하는지 설명하는 것을 넘어서 설계 결정 사항과 코드 작성시 택한 트레이드오프를 문서화함으로써 여러분이 무슨 일을 했고 왜 그렇게 했는지 설명해 줍니다.

- 54 p

 

코드베이스가 진화할수록 과거에 내린 결정의 맥락을 남겨두는 것이 도움이 됩니다. 코드가 특히 복잡한 경우 앞에 한 줄의 인라인 코드 주석이라도 있으면 훗날 코드를 볼 개발자들이 시간을 많이 절약할 수 있습니다.

- 55 p

 

코드는 결코 완벽하지 않기에 코드 자체만으로 문서화가 되는 경우는 거의 없습니다.

- 55p 

 

 

 

README는 다음과 같은 기본 정보를 담고 있습니다. 

• 코드가 상위 수준에서 하는 일
• 설치 방법
• 문제 해결 단계
• 코드 유지 관리자
• 라이선스 정보
• 변경 로그
• 기본 사용 예시
• 심화 자료와 문서 링크 

- 56p 

 

 

시작하기 문서, 개념 문서, 절차 문서, 참조 문서 

- 57~70p 

 

 

 

문서의 가장 앞부분에 이미 수집한 정보를 나열하여 문서를 시작할 수 있습니다.

• 독자
• 목적
• 콘텐츠 패턴 

- 79 p

 

 

제목을 만들때는 다음 요령을 명심하세요.

• 최대한 간결하고 명확하고 구체적이어야 합니다.
• 가장 중요한 정보를 앞에 배치합니다.
• 각 절에 대해 고유한 제목을 사용합니다.
• 일관성을 유지합니다.

- 85p 

 

 

기술적 정확성을 위한 편집, 완전성을 위한 편집, 구조 측면에서의 편집, 명확성과 간결성을 위한 편집

- 100~110p

 

 

 

좋은 샘플 코드는 그것을 설명하는 글보다 더 많은 내용을 전달하는 동시에, 독자들이 참고하여 코드 작성의 기반으로 삼을 만한 유용한 틀을 제공할 수 있습니다.

- 121p 

 

 

조직에서 동료 리뷰와 자동화된 테스트를 거친 다음에 코드를 릴리스한다면, 문서 또한 유사한 절차를 거쳐서 릴리스해야 합니다. 절차의 일관성을 보장하는 가장 간단한 방법은 문서화를 위해 코드 리뷰 프로세스를 사용하는 것입니다.

- 168p 

 

 

 

구글의 연구 그룹은 소프트웨어 테스트 분야에서 사용되는 용어를 가져와서 문서 품질을 두가지 기본 범주로 분류했습니다.

• 기능적 품질은 문서가 목적이나 목표를 달성하는지를 의미합니다.
• 구조적 품질은 문서가 잘 작성되고 잘 구조화되었는지를 의미합니다.

- 194p 

 

 

테크니컬 라이팅은 기술 정보를 가공하여 독자가 소화하기에 적합한 문서로 만드는 일입니다.

- 248p 

 

 

명확성, 간결성, 일관성이라는 세 가지 원칙에 따라 문서를 만들어야 하고, 문서 작성의 중요성을 인식하고, 독자가 쉽게 이해할 수 있도록 하는 것이 매우 중요합니다.

- 256 (우아한 형제들 유영경)

 

 

Q. 테크니컬 라이팅에 꼭 필요한 점과 지켜야 하는 점은 무엇이라고 생각하시나요?

A. 저에게 테크니컬 라이팅에서 가장 중요한 것은 스토리텔링에 맞춘 목차 구성이에요. 처음 문서화 프로젝트가 주어지면 당연히 주제를 분석하고, 독자를 파악한 후에 어떤 정보들을 전달하고 싶은지, 어떤 내용의 흐름으로 전달할 것인지를 생각해요. 처음부터 글을 쓰는 게 아니라, 전달하고 싶은 핵심 단어를 나열을 해보고 비슷한 주제로 그룹화를 해요. 어느 정도 틀을 만들어 보면 문서 전체에 흐름이 나타나고, 어떤 내용으로 이어나갈 수 있을지 감이 오죠. 목차의 구성은 테크니컬 라이팅에 꼭 필요한 부분이면서 가장 중요한 부분이라고 할 수 있어요. 

- 262(카카오엔터프라이즈 김유리)p 

 

 

개인적으로 테크니컬 라이팅에 필요한 것을 아마존의 Leadership principles 중에 고르자면, 항상 새로운 것을 문서화해야 하므로 끊임 없이 배우는 자세 'Learn and be curious', 엔지니어와 프로덕트 매니저들을 대신하여 대중에게 제품을 설명한다는 책임감 'Ownership', 그리고 언제나 독자를 우선해 제품 사용에 진입 장벽을 낮춰 'Customer obsession'를 추구하는 자세가 필요하다고 생각합니다. 

- 267(AWS 최미영)

 

 

정확하고 읽기 편한 글을 쓰는 거죠. 테크니컬 라이팅의 본질적인 목표는 복잡하고 어려운 것을 쉽게 기술하는 것이거든요.

- 271(라인 전정은)p 

 

 

이 지식의 반감기는 분야마다 차이가 있지만, IT 분야는 다른 분야에 비해 지식의 유통기한이 매우 짧습니다. 그렇기 때문에 흔히 '개발자는 평생 동안 공부해야 하는 직업'이라고 말합니다.

- 283(NHN 박선영)p 

 

 

기술 문서의 작성 목적은 서로 다른 기술 스택을 보유한 개발자 모두가 협업의 본질을 이해하고, 해당 업무가 처음이더라도 원활하게 일할 수 있는 훌륭한 가이드나 매뉴얼을 남기는 것입니다.

- 302(넷마블 이중민)p 

 

 

 

참고자료

 

교육 과정 

• 구글의 테크니컬 라이팅 교육 과정: developer.google.com/tech-writing
• API 문서화하기: 테크니컬 라이터와 엔지니어를 위한 가이드: www. idratherbewriting.com/learnapidoc

템플릿

• The Good Docs Project: www.thegooddocsproject.dev
• Diataxis 프레임 워크: www.diataxis.fr 
• README 체크리스트: www.github.com/ddbeck/readme-checklist

 

스타일 가이드

• 구글 개발자 문서 스타일 가이드: developer.google.com/style
• 마이크로소프트 스타일 가이드: docs.microsoft.com/style-guide 
• 미디어위키 스타일 가이드: mediawifi.org/wiki/Documentation

 

자동화 도구

• API 레퍼런스 생성 : openapis.org, redoc.ly, swagger.io 
• Vale 린터: github.com/errata-ai/vale
• htmltest: github.com/wjdp/htmlteest
• Read the Docs: readthedocs.org
• Docsy: docsy.dev
• Netlify: netlify.com
• Prow: github.com/kubernetes/test-infra/tree/master/prow

 

시각적 콘텐츠 도구 및 프레임워크

• Excalidraw: excalidraw.com
• Snagit: snagit.com
• C4: c4model.com 

 

블로그 및 연구 

• 톰 존슨: idratherbewriting.com
• 밥 왓슨: docsbydesign.com
• 사라 매덕스: ffeathers.wordpress.com
• 다니엘 벡: ddbeck.com/writing
• 스테파니 모릴로: stephaniemorillo.co/blog
• 닐슨 노먼 그룹: nngroup.com/articles 

 

커뮤니티

• write the docs : www.writethedocs.org
• stc: www.stc.org

 

국내자료 

• 한국공개소프트웨어협회 BSB 테크니컬 라이팅: https://olc.kr/course/course_online_view.jsp?id=10108
• 한겨레 글터 : http://pen.hanter21.co.kr -> Technical Writing 검색 
• 카카오엔터프라이즈 블로그: https://tech.kakaoenterprise.com/tag/Technical%20Writer
• 라인 엔지니어링 블로그: https://engineering/linecorp.com/ko/blog/tag/Technical%20Writing
• 열이아빠 블로그: https://koko8829.tistory.com/category/테크니컬%20라이팅
• Write the docs seoul: https://www.facebook.com/groups/writethedocsseoul

 

- 320~330p