메뉴 바로가기 검색 및 카테고리 바로가기 본문 바로가기

한빛출판네트워크

Docs for Developers 기술 문서 작성 완벽 가이드

우아한형제들 카카오 등 국내 테크니컬 라이터 11인 인터뷰 특별 수록

한빛미디어

번역서

판매중

  • 저자 : 자레드 바티 , 재커리 사라 콜라이센 , 젠 램본 , 데이비드 누네즈 , 하이디 워터하우스
  • 번역 : 하성창
  • 출간 : 2023-04-10
  • 페이지 : 332 쪽
  • ISBN : 9791169210881
  • 물류코드 :11088
  • 초급 초중급 중급 중고급 고급
4.9점 (28명)
좋아요 : 27

소프트웨어 개발자를 안내하는 테크니컬 라이팅을 위한 실무 노트

 

우아한형제들, 카카오, AWS, LINE Plus, 쿠팡, NHN, 데브시스터즈, 넷마블 등 국내 테크니컬 라이터 11인 인터뷰 특별 수록!

 

이 책은 ‘강아지 음성 번역 서비스’를 만드는 개발 팀의 스토리를 따라가며, 개발 문서를 만드는 과정을 단계별로 배우도록 구성되었습니다. 단계별 예제, 템플릿, 가이드를 통해 이론적인 내용뿐만 아니라 문서를 효과적으로 작성하고 관리하는 방법도 배우게 됩니다. 단계에 맞는 문서화 기술을 배우고, 사용자 니즈 이해부터 문서 작성, 유용한 개발자 문서 배포 및 유지까지 프로젝트 관리와와 소프트웨어 개발 라이프사이클 전체를 한 권에 담아 설명합니다. 

또한 부록에는 우아한형제들, LINE Plus, 카카오엔터프라이즈, NHN 클라우드, 넷마블, 데브시스터즈, AWS, 쿠팡에서 활동하는 국내 유명 테크니컬 라이터 11인의 인터뷰가 수록되었습니다. 테크니컬 라이팅이 무엇인지, 업계에서 테크니컬 라이터의 역할에 대해 설명합니다. 이미 테크니컬 라이팅의 세계를 경험한 선배들의 다양한 경험과 이야기를 들을 수 있습니다.

 

detail_image.jpg

 

자레드 바티 저자

자레드 바티

구글 클라우드 문서 팀의 공동 설립자다. 지난 14년 동안 구글에서 다양한 프로젝트를 문서화하는 데 기여했다. 현재는 웨이모에서 기술 문서 작성 업무를 이끌고 있다. 

재커리 사라 콜라이센 저자

재커리 사라 콜라이센

리눅스 재단 수석 테크니컬 라이터였고, 책을 마무리할 시점에는 스트라이프의 수석 스태프 테크니컬 라이터가 되었다. 2017년부터 2021년까지 쿠버네티스 문서화 프로젝트 공동 의장을 역임했으며, 그 전까지는 깃헙, 랙스페이스 및 여러 스타트업에서 개발자 문서를 만들었다.

젠 램본 저자

젠 램본

몬조 뱅크에서 테크니컬 라이팅 및 지식 관리 부서를 이끌고 있다. 핀테크 분야에 진출하기 전에는 GDS의 테크니컬 라이팅 책임자로서 영국 정부 전체의 문서 관리자 커뮤니티를 이끌었다.

데이비드 누네즈 저자

데이비드 누네즈

스트라이프에서 테크니컬 라이팅 조직을 이끌고 있으며, 내부 문서화 팀을 설립하고 『인크리먼트』 잡지에 글을 기고하기도 했다. 우버에서 테크니컬 라이팅 조직을 설립하고 이끌었으며, 세일즈포스에서 문서화 리더 역할을 맡았다.

하이디 워터하우스 저자

하이디 워터하우스

수십년 동안 마이크로소프트, 델 소프트웨어 및 수많은 스타트업에서 개발자와 소통하고 개발자를 위해 소통하는 방법을 배웠다. 현재 론치다클리에서 수석 디벨로퍼 릴레이션 담당자로 일하고 있다.

하성창 역자

하성창

컴퓨터 기술을 다루는 글쓰기와 번역 일을 하고 있다. 주로 테크니컬 라이터로 일했고, 소프트웨어 개발자와 로컬라이제이션(제품 현지화) 담당자로 일하기도 했다. 시간이 날 때는 집에서 음악 듣기를 즐긴다.  『유닉스의 탄생』과 『1일 1로그 100일 완성 IT 지식』을 번역했다.

CHAPTER 1 독자 이해하기 

_Corg.ly 애플리케이션 출시 한달 전 

_지식의 저주 

_사용자 밑그림 그리기 

_사용자 이해 검증하기 

_사용자 조사 결과 압축하기 

_마찰 로그 만들기 

_요약

 

CHAPTER 2 문서화 계획하기 

_Corg.ly 애플리케이션 문서화 계획 만들기 

_문서화 계획과 패턴 

_콘텐츠 유형 

_요약 

 

CHAPTER 3 문서 초안 만들기

_Corg.ly 애플리케이션 첫 번째 초안 

_빈 페이지(화면) 대면하기 

_성공적인 문서 작성을 위해 준비하기 

_개요 작성하기 

_초안 작성하기 

_훑어보기를 고려하여 문서 작성하기 

_막혔을 때 빠져나오기 

_템플릿으로 작성 시작하기 

_첫 번째 초안 완성하기 

_요약 

 

CHAPTER 4 문서 편집하기

_Corg.ly 애플리케이션 콘텐츠 편집하기 

_사용자의 니즈에 맞춰 편집하기 

_편집에 대한 여러 가지 접근법 

_편집 프로세스 만들기 

_피드백 받아서 반영하기 

_좋은 피드백 제공하기 

_요약 

 

CHAPTER 5 샘플 코드 통합하기 

_Corg.ly 애플리케이션 어떻게 작동하는지 보여주기 

_샘플 코드 사용하기 

_샘플 코드의 유형 

_좋은 샘플 코드의 원칙 

_샘플 코드 설계하기 

_샘플 코드를 위한 도구 

_요약

 

CHAPTER 6 시각적 콘텐츠 추가하기 

_Corg.ly 애플리케이션 백 마디 말보다… 

_말로는 부족할 때 

_시각적 콘텐츠를 만들기 어려운 이유 

_스크린샷 사용하기 

_일반적인 다이어그램 유형 

_다이어그램 그리기 

_비디오 콘텐츠 만들기 

_시각적 콘텐츠 검토하기 

_시각적 콘텐츠 유지 관리하기 

_요약

 

CHAPTER 7 문서 배포하기

_Corg.ly 애플리케이션 배포! 

_콘텐츠 선보이기 

_콘텐츠 릴리스 프로세스 구축하기 

_배포 타임라인 만들기 

_앞날을 위해 준비하기 

_요약 

 

CHAPTER 8 피드백 수집하고 통합하기

_Corg.ly 애플리케이션 첫 번째 피드백 

_사용자 의견에 귀 기울이기 

_피드백 채널 만들기 

_피드백에 대해 조치 취하기 

_요약 

 

CHAPTER 9 문서 품질 측정하기

_Corg.ly 애플리케이션 출시 다음 주 화요일 

_내가 쓴 문서가 괜찮은 걸까? 

_문서 품질 이해하기 

_분석을 위한 전략 세우기 

_문서 메트릭 사용 팁 

_요약 

 

CHAPTER 10 문서 구조화하기

_Corg.ly 애플리케이션 다음 릴리스 

_독자를 위해 문서 구조화하기 

_독자가 길을 찾도록 돕기 

_문서 구조화하기 

_요약

 

CHAPTER 11 문서 유지 관리 및 지원 중단하기  

_Corg.ly 애플리케이션 몇 번의 릴리스 후 

_문서를 최신으로 유지하기 

_유지 관리를 위한 계획 세우기 

_문서 유지 관리 자동화하기 

_콘텐츠를 문서 세트에서 제거하기 

_요약 

 

부록 A. 국내 테크니컬 라이팅은 어떨까요? 


부록 B. 전문가를 고용해야 하는 경우

부록 C. 참고 자료

특별 부록 : 국내 테크니컬 라이터 11인 인터뷰 

 

「자꾸 쓰다 보면 잘 쓸 수 있습니다」  

- 유영경 <우아한 형제들>

 

「기술 문서를 책임지는 사람들, 테크니컬 라이터」 

- 김유리 <카카오엔터프라이즈>

 

「AWS 머신러닝 테크니컬 라이터가 된 천체물리학 박사의 이야기」 

- 최미영 <AWS> 

 

「2세대 테크니컬 라이터의 이야기」 

- 전정은 <LINE Plus> 

 

「테크니컬 라이터가 가져야 하는 자세」 

- 임근희 <쿠팡>

 

「직업으로서의 테크니컬 라이터」 

- 박선영 <NHN 클라우드>

 

「LINE에서 테크니컬 라이터가 하는 일」 

- 이인실 <LINE Plus> 

 

「테크니컬 라이터의 자세」 

- 남정현 <데브시스터즈>

 

「IT 기업 테크니컬 라이터의 경험과 짧은 소회」 

- 강정일 <LINE Plus>

 

「테크니컬 라이터의 이야기」 

- 이중민 <넷마블>

 

「테크니컬 라이터도 그냥 흔한 동료 중 한 명입니다」 

- 조병승 <넷마블>

 

개발 생태계 모든 사람을 위한 

이야기로 배우는 기술 문서 작성법

 

좋은 문서화와 프로그래밍을 통합하는 것은 중요합니다. 문서화가 잘된 프로젝트는 개발자와 사용자 모두에게 도움을 줍니다. 적절한 기술 문서가 없는 프로젝트에서는 개발자 생산성, 프로젝트 확장성, 사용자의 제품 채택률과 접근성이 저하될 뿐만 아니라 프로젝트 성공 확률까지 낮아집니다. 그만큼 프로젝트 진행에 있어 좋은 문서화는 필수 조건입니다. 

 

이 책은 가상의 소프트웨어 개발 팀이 새 제품을 출시하는 과정에 따라 개발자 문서를 만드는 과정을 설명합니다. 사용자의 니즈를 조사하고, 일반적인 문서화 패턴에 따라 계획 수립부터 콘텐츠 초안 작성과 편집 후 배포하는 과정까지 알려줍니다. 배포 후에도 피드백을 취합하고, 문서의 유효성을 측정하는 등 문서의 규모가 커짐에 따라 유지 관리하는 데 필요한 실용적인 조언을 함께 제공합니다. 

 

또한 원서에는 담기지 않았던 국내 유명 테크니컬 라이터 11인의 인터뷰를 수록하여, 다양한 회사에서 일하는 테크니컬 라이터들의 업무 이야기와 자신의 경험을 바탕으로 선배 테크니컬 라이터로서 도움이 될만한 이야기도 함께 제공합니다.  

 

대상 독자 

- 코드와 함께 문서를 작성해야 하는 소프트웨어 개발자

- 제품 및 서비스 전반을 파악해야 하는 프로덕트 매니저, 디벨로퍼 릴레이션 담당자

- 개발 경험이나 지식을 공유하고 싶은 기술 블로그 운영자

- 제품 및 서비스에 관한 문서를 작성하는 테크니컬 라이터 

- SI 제안서를 써야하는 외주 개발자

 

이 책에서 다루는 내용

- 마찰 로그를 만들고 사용자 조사를 진행하여 사용자의 니즈를 파악합니다.

- README, API 문서, 튜토리얼, 개념 문서, 릴리스 노트를 포함하여 다양한 종류의 문서를 조사하고, 초안을 만들고 최종 콘텐츠를 작성합니다.

- 문서 배포 후, 사용자 피드백을 통해 콘텐츠의 품질을 유지 관리합니다.

- 프로젝트 과정을 따라가며 단계별 해야 할 업무에 대해 정리합니다.

실제로 문서화 할때 겪는 문제들을 그대로 풀어주기 때문에 읽으면서 공감이 많이 되었다.

앞으로 문서를 이렇게 작성해야겠다 생각되는 부분도 많았다.

국내 테크니컬 라이터들의 이야기도 흥미로운데, 기업간 문화 차이에 "글"이 얼마나 큰 영향을 주는지 간접적으로 느낄수 있었다.

여유될때 한번 읽어보면 좋은 책이다.

한빛미디어 <나는 리뷰어다> 활동을 위해서 책을 제공받아 작성된 서평입니다.

 

글을 쓴다는 것은, 개인의 행한 것을 정리하는 것도 되지만,

아는 것을 정리하며 다시한번 내 것으로 하는 행위이기도 하다.

 

개발자로서 일을 하면서, 단순히 개발만 하면 끝이라 생각할 때가 있었다.

하지만 업무를 하다보면 개발만큼 중요한 일이 문서 작성이었고, 이 책에선 이 문서를 어떻게 작성해야 하는가에 대해서 하나하나 예시와 함께 정리해 알려주기에, 개발자 필독서로서 꼭 한번쯤 읽어봐야 할 필요가 있다 생각한다.

 

기술문서의 작성과 개발은 떨어지지 않고, 개발자 본인을 위해서 이니까.

 

IMG_2536.jpg

 

 

이번에 읽은 책은 기술문서 작성 완벽가이드 라는 책이다. 요즘 회사에서 여러가지 작업한 것들, 진행했던 것들을 새로 정리하고 가다듬는 필요가 있을 것 같아서 어디 좋은 책 없나 찾았다. 때마침 좋은 책이 나와서 신청해서 읽어봤다.

 

 

진짜 평소에 이렇게 쓰면 좋지 않을까 하면서 생각하던 내용들이 훨씬 더 잘 명료하게 정리되어 있었다. 다양한 형식에서 이렇게 쓰면 좋다 하는 내용들을 압축해서 담아놨다. 이거 읽고 나서 확실히 도움이 많이 되는 것 같다.

 

적절한 예시와 요점들을 눈에 띄게 편집해둬서 참 보기 편했던 것 같다.

 

깃허브 같은데에서 많이 보던 Readme 나 release note 같은 것들도 작성할때 사실 크게 신경쓰지 않고 작성했었고, 사내 기술 문서를 작성할때도 나름 많이 고치고 읽는 사람들을 고려해서 쓴다고 했지만, 이 책에서 말하는 것들을 보면서 참 많이 돌아보게 되는 것 같다.

 

 

"한빛미디어 <나는 리뷰어다> 활동을 위해서 책을 제공받아 작성된 서평입니다."

	"한빛미디어 <나는 리뷰어다> 활동을 위해서 책을 제공받아 작성된 서평입니다

 

 

문서화, 모든 개발자의 숙제이다. 필요한 이유는 알고있지만 하기 싫고 귀찮은 작업 중하나이다. 소프트웨어 개발 산출물 중 하나이기도 하고 다른 개발자 혹은 미래의 자신을 위해서 필요한 작업이기도하다. 

필요성을 인지하고 있기때문에 모두 작성을 하려고하긴 하지만 어떻게 작성해야하는지를 잘 모른다. 책의 서두에도 나오는 '지식의 저주' 때문에 '이런것은 이미 알고있겠지' 혹은 '이렇게 자세히 쓰면 아무도 안읽을거야' 같은 생각을 하게된다. 

사실 이책의 내용의 대부분은 이미 알고 있는 이야기였다. 그럼에도 이 책은 나에게 도움이 되었다. 왜냐면 "왜?"에 대한 답을 주기 때문이다. 문서화를 하다가 동료팀원에게 보완점을 이야기 했을때 "왜 그렇게 해야하죠?" 라는 말에 대답을 못하는 경우가 있다. 왜냐면 내 기준에선 당연한 이야기 이기 때문이다. 물론 '당연히 그렇게 해야죠'라는 말을 하면 싸움밖에 안날것이기때문에 당황하는 경우가 있었는데 이 책은 왜 그렇게 해야하는지에대해 알려주기 때문에 속이 시원해지는 경험을 했다.

이미 알고는 있지만 왜인지 몰랐던 문서에 대한 이야기들은 큰 도움이 되었다. 물론 내가 몰랐던 이야기들도 있었고, 문서화 방향에 대한 가이드이기 때문에 큰 도움이 되었다. 

내용이 어렵지도 않고 술술 잘 읽히니 시간이 날때 카페에서 커피 한잔과 함께 가볍게 읽어보면 좋은 책이다. 

한빛미디어 <나는 리뷰어다> 활동을 위해서 책을 제공받아 작성된 서평입니다.

Intro

나는 예전에 개발자라면 그저 개발만 잘하면 되는 건 줄 알았다. 그러나 실상은 그렇지 않았다. 선배 개발자분들이 쓰신 책들을 통해 협업이라는 것을 해야 된다는 것을 알게 됐고, 또한 서로 의 소통을 해야 한다는 것을 알게 됐다. 이 소통이 그저 말로 하는 커뮤니케이션이라고 생각할 수도 있겠지만, 문서를 통해 소통하는 경우도 많다고 한다. 그렇기에 나는 문서를 잘 쓰는 것 또한 개발자에게 개발하는 것만큼 중요한 능력이라 생각했고 이 책을 선택하게 되었다.

Book Review

누구를 위한 문서인가

이 책은 '우리가 작성하고 있는 문서를 읽는 사람은 누구인가?'를 계속 상기시켜 주는 책이다. 이 책은 지식의 저주를 강조한다. 마블의 영화를 봤다면 알 것이다. 간단하게 설명하면 내가 아는 것을 상대방도 알 것이라고 생각하는 것이다. 문서를 읽는 사람이 내가 작성한 코드와 설명에 대해 이해하고 있을 거라고 생각하지 말고, 독자의 눈높이에 맞게 기술 수준을 풀어서 설명하라고 말한다. 결국 독자가 알고 싶어 하는 것을 명확하고 간결하게 전달하는 것이 중요하다는 것이다.

간단한 구성과 반성

이 책은 'Corg.ly'라는 가상의 프로젝트를 설정하고 출시 전부터 출시 후까지의 내용을 다룬다. 그 과정에서 어떻게 개발 문서를 작성하고 개선하는지 알려준다.

이 책을 읽으면서 지금까지 내가 썼던 문서들에 대해서 반성을 하게 됐다. 대개 '내가 쓴 문서들은 그래도 개발자가 읽을 테니까 대충이라도 이 기술에 들어봤고 관심이 있을 것이다.'라고 생각하고 쓴 글들이 많다. 책 리뷰도 마찬가지라는 것을 알게 됐고, 앞으로 글을 어떻게 작성해야 할지 고민하게 됐다.

부록

부록은 국내 테크니컬 라이팅에 관한 내용, 전문가를 고용해야 하는 경우, 참고 자료. 즉, 총 3가지가 제공된다. 나는 특히 국내 테크니컬 라이팅에 관한 내용이 마음에 들었다. 난 테크니컬 라이터라는 직업에 대해서 단편적으로 알고 있었으며, 정확히 어떤 일을 담당하고 있는지 몰랐다. 그러나 부록인 국내의 테크니컬 라이터 11분의 인터뷰를 통해 이 직업에 대해 더욱 자세하게 알게 됐고, 이 직업에 대해 흥미도 생기게 됐다. 솔직히 테크니컬 라이터가 되기 위한 분들은 부록만 해도 이 책의 가치는 충분하다고 생각한다.

대상 독자

자신이 개발한 것들을 자주 문서화해야 하는 사람들에게 추천한다. 그 이외에도 테크니컬 라이터가 되고 싶어하는 분들께도 이 책을 추천한다. 위에서도 언급했듯이 부록에 현업에서 일하시고 있으신 국내 테크니컬 라이터 11분의 인터뷰가 담겨 있기에 테크니컬 라이터가 되고 싶어 하는 분들께도 이 책을 추천하고 싶다.

 

한빛미디어 <나는 리뷰어다> 활동을 위해서 책을 제공받아 작성된 서평입니다.

 

Docs for Developers 기술 문서 작성 완벽 가이드는 Corg.ly라는 가상의 서비스를 만드는 개발 팀에 대한 이야기를 들려주고 있다. Corg.ly 는 강아지 음성을 인간의 언어로 번역하는 서비스이다. API를 사용하여 번역을 요청하고 번역 결과를 받으며, 머신 러닝 모델을 사용하여 정기적으로 번역을 개선한다. 

 

 

그리고 이 책에서는 특정 도구나 프레임워크를 다루지 않는다. 문서를 특정 마크업 언어로 작성하거나 특정 CI, 지속적 통합 도구로 자동 업데이트되는 특정 정적 사이트 생성기로 문서를 게시하는 방법을 알려주지 않는것에 대해 실망스러워하실 분도 있을 수 있다. 하지만 이렇게 한 이유는 문서화에 가장 효과적인 언어와 도구는 독자가 작성하는 코드 및 개발 도구와 밀접한 연관이 있고, 이는 독자가 처한 환경에 따라 달라지기 때문이라고 설명한다. 

 

도구 선택에 대한 지침이 추가로 필요한 독자를 위해 책의 끝에서는 요구 사항에 맞는 문서화 도구와 추가 정보를 찾는 데 사용할 수 있는 자료를 부록으로 제공하고 있다. 

 

Corg.ly 서비스를 출시하고 운영하는 과정을 팔로우하면서 개발자 문서 작성 방법을 쉽고 재밌게 배울수 있었다. 

 

 

700

 

 

 

개발 처음 배울 때는 코딩만 잘하면 되는 줄 알았다 (그 조차도 못함)

 

개발자는 은둔하고 소심한 체크남방 남자의 삶일 줄 알았으나

의외로 정말 많은 발표, 문서화를 경험하게 됐다.

 

개발자끼리는 API 명세서를 포함한 각종 문서를 만들어야했다.

최근엔 소마를 하게 되면서 기획서를 만들고, 발표 준비를 했다.

내 생각을 전달하는 방법이 몹시 중요하다.

 

무슨 문서든 똑같다.

기획서를 작성하라고 시킴 당하고(?) API 명세서를 만들라고 강요당하면 벙찐다.

 

피드백을 받을 때 꽤나 많이 들어봤고, 나도 많이 고민하는 것은

 

우리는 오랫동안 고민하면서 익숙해졌지만

듣는 사람들은 이 내용이 뭘 말하는 지 모른다는 사실이다.

이 책에서는 “지식의 저주”라는 표현을 쓴다. 정말 적합한 말이 아닐까?

 

독자가 고급 개발자라면? 초급 개발자라면? 일반인이라면? 이런 고민을 하고

고민을 넘어서 감정을 이입해야한다.

디자인씽킹도 그렇고, 기획에 대해서도 고민하는 것도 그렇고 이런 문서화를 할 때에도

결국에는 감정이입이 중요하다.

 

후반에는 국내 테크니컬 라이팅을 하는 분들의 인터뷰가 나온다.

굉장히 딱 와닿는 표현을 봤다.

문서도 ‘제품’이다.

개발이든 제품이든 만들면서 파생되는 부수적인 작성물이 아니구나 라고 느꼈다.

 

의외로 많은 생각을 하게 짧은 책이었다고 생각한다. 좋았다.

우리는 기획하고, 디자인하고, 개발을 할 때 사용자 중심으로 생각하는 연습을 계속하게 된다. 즉 프로덕트의 최종 사용자를 생각하며 프로덕트를 생산하는 것. 그게 우리가 해야 하는 일이다.

마찬가지로 개발 과정 중 협업을 위해 다른 도메인의 직무들과 소통할 때 흔히 문서를 주고받게 되는데, 이 때 소통 문제가 발생하지 않도록 신중한 문서 작성이 필요하다.

 

이 책에서 가장 먼저 소개하는 것은 '지식의 저주(Curse of Knowledge)'이다. 거창해보이지만, 사실 내가 아는 걸 상대방도 알거라는 착각을 벗어던지라는 의미이다. 잘 알기에 전문용어를 남발하는 것을 포함하는 내용이다.

팀 프로젝트를 하다보면 흔히 겪을 수 있는 커뮤니케이션 오류 중 하나로, 내가 작성한 코드, 내가 조사한 자료에 대해 상대방도 어느 정도 이해하고 있을 거라는 착각에서 벗어나 상대방을 먼저 이해하고, 문서화를 계획하고, 초안 작성, 편집 등등 개발자 문서 전반에 대한 소개를 하고 있다. 책에서 예시는 강아지 언어 번역 서비스 API 개발팀의 스토리를 기반으로 진행되며, 개발 문서를 작성하는 과정을 단계별로 배우도록 소개한다. 번역된 책이다보니 다소의 번역투가 남아있어 신경쓰일 수는 있지만, 책의 전반적인 내용과 흐름을 이해하기에는 부족하지 않으니 개발문서 작성에 관심있는 사람이라면 읽어보면 좋을 것 같다.

Docs for Developers 기술 문서 작성 완벽 가이드

 

이 책에서 눈에 띄는 주제 중 하나는 "지식의 저주"라는 개념입니다. 주제에 대해 이미 깊이 알고 있는 상태에서 다른 사람에게 무언가를 설명하는 것이 어렵다는 것을 의미합니다. 이 책은 이 저주를 인식하고 작가와 독자 사이의 이해 격차를 해소하기 위한 조처를 하는 것의 중요성을 강조합니다. 명확한 설명을 제공하고 전문 용어나 가정을 피함으로써 기술 문서 작성시 자신의 문서를 다양한 청중이 액세스할 수 있도록 할 수 있습니다.

 

 

이 책은 또한 기술 문서 작성의 협업적 특성을 강조합니다. 어떤 문서도 고립되어 존재하지 않는다는 사실을 강조합니다. IT 환경에서는 상호 연결된 여러 문서가 있는 경우가 많으며 독자를 관련 자원으로 안내하고 필요한 정보에 쉽게 액세스할 수 있도록 하는 것이 중요합니다. 문서를 효과적으로 구성하고 탐색 요소를 통합함으로써 작성자는 독자가 원활하게 탐색하고 혼란이나 좌절 없이 원하는 정보를 찾을 수 있도록 도울 수 있습니다.

 

 

또한 이 책은 문서가 발전하고 정기적으로 업데이트되어야 할 필요성을 강조합니다. 기술은 끊임없이 변화하고 있으며 오래되었거나 부정확한 문서는 혼란과 오류로 이어질 수 있습니다. 기술 문서는 독자가 자신의 문서에 두는 신뢰를 염두에 두고 제공된 정보가 신뢰할 수 있도록 해야 합니다. 문서 작성 및 유지 관리는 시간이 많이 소요될 수 있지만 효과적인 의사소통을 지원하고 사용자 간의 신뢰를 조성하는 것은 필수적인 책임입니다.

 

 

결과적으로 기술 전문성 수준에 관계없이 기술 문서 작성에 관련된 모든 사람에게 유용한 책입니다. 특히 IT, 오픈 API 명세를 작성하는 분에게 적합합니다.

 

  "한빛미디어 <나는 리뷰어다> 활동을 위해서 책을 제공받아 작성된 서평입니다."

0. 들어가기에 앞서

한빛미디어 <나는 리뷰어다> 활동을 위해서 책을 제공받아 작성된 서평입니다.

제목 : Docs for Developers 기술 문서 작성 완벽 가이드 
저자 : 자레드 바티 외 4명 번역 : 하성창 출판사 : 한빛 미디어
출간 : 2023년 4월 10일
페이지 : 332


1. TL;DR

  • 책의 내용이 적당하며, 발췌독 하기 좋습니다..
  • 책의 챕터 단위가 그렇게 크지 않기에 마음 편히 읽을 수 있습니다.
  • 본인이 공부한 기술적인 내용에 대한 글쓰기 책이 아닙니다. 카카오 지도 API 문서, 채널톡 API 문서 등 이런 API 문서를 작성해야 하는 사람이라면 읽어 보는걸 추천합니다.
  • 그렇지만, 기술적인 글쓰기에 대해 공부해 보고 싶은 분들에게도 좋은 책입니다. 개발자들도 가벼운 마음으로 읽어봐도 좋을 것 같습니다.

2. 이 책을 선택한 이유

이직을 하고 나서 좋았던 점 중 하나는 사내 위키가 활성화 되어 있다는 점 이었습니다. 그러나 위키가 잘 되어 있는 것과 별개로 필요한 정보가 어디에 있는지 찾는건 어려운 일이었습니다. 또한 의미 있는 정보를 기술하는 방식에 있어서 천차 만별이었으며, 저 또한 어떻게 사내 위키에 제가 배운, 추가해야 할 내용을 기술할지 고민이 었습니다. 그렇기 때문에 이 책 기술 문서 작성 완벽 가이드를 읽고 어떻게 문서를 작성 할 것인지 고민해 보기로 했습니다.

3. 리뷰

이 책은 반려동물 소리를 텍스트로 번역해주는 회사를 예시로 들어 책의 내용을 설명합니다. 내부 개발자를 위한 기술 문서가 아닌 외부 상품으로 판매되는 소프트웨어 API 문서를 기준으로 설명을 하고 있습니다.

이 책에서는 단순히 기술 문서를 작성하기 위한 테크닉을 넘어 다양한 것들을 알려주려고 합니다. 문서를 읽는 독자, 독자의 니즈, 독자가 알아야 하는 것 등 독자분석으로 컨텐츠를 시작합니다.

독자 분석이 끝나고 나면 이제 분석한 독자를 기반으로 어떤 컨텐츠를 만들지 컨텐츠에 대해 설명해 줍니다. 그 컨텐츠의 장단점 및 특징을 설명함으로써 독자를 정의 하고 난 이후 어떤 양식의 컨텐츠를 선택할 지 정합니다.

컨텐츠를 정하고 나면, 컨텐츠에 맞는 내용을 기술해야 합니다. 여기서 템플릿이 나옵니다. 잘 작성된 템플릿의 내용과 잘 작성되지 않은 템플릿 내용을 확인할 수 있습니다.

개인적으로 저는 예전에 숱히 읽었던 개발 공식 문서들을 비교해보며, 아 이 개발 문서는 잘 작성되었구나, 아 그 공식문서는 잘 작성되지 않았구나 라는 것을 평가하며 읽을 수 있었습니다.

개인적으로 기술 문서 작성이라고 하길래 기술적인 내용을 작성하는 방식이라고 생각했지만, 외부에 노출시키는 기술 문서를 작성하는 것이라 기대했던 바와는 조금 달랐습니다.

그러나 기술적인 내용 글쓰기에 대해 이론적인 내용과 테크니컬한 방법을 배울 수 있었다는 점이 좋았습니다.


4. 총평

  • 카카오 지도 API, 채널톡 API등의 API 문서를 작성해야 하는 사람들에게 적절한 책 입니다.
  • 기술 글쓰기에서 우리가 생각하지 못한 이론적인 부분과, 테크니컬한 부분도 설명해 줘서 읽기 편합니다.
  • 책의 모든 부분이 필요한게 아니니 발췌독이 필요한 경우에는 발췌독 해서 읽을 것 ! (그러나 1 ~ 4장은 다 읽어 보기를 추천 합니다.)
  • 이 책을 읽다 보면 글을 쓰고 싶어질 수 있으니, 공책 같은 것도 미리 준비해 두면 좋습니다.

 

기술 문서를 작성하는 법에 대한 내용을 담고 있는 'Docs for Developers 기술문서 작성 완벽가이드'라는 책입니다. 개발자들이 개발을 하면서 매일 같이 접하게 되는 공식문서가 사실 기술문서인데요. 공식문서를 보면 A 공식문서는 이해가 엄청 잘 되고 깔끔하게 쓰여졌다는 느낌이 들기도 하지만, B 공식문서는 뭔가 가독성이 좋지 않고 내가 찾고 싶은 내용을 찾는 게 어렵다고 느껴질 때도 있습니다. 이 책을 읽으면서 왜 쉽게 읽히고, 어렵게 읽히는지에 대한 이유를 알 수 있었던 것 같습니다. 또 잘 읽히는 기술문서를 작성하기 위해서는 어떻게 해야할 지에 대한 방법도 알 수 있었습니다.

 

이 책은 '강아지 음성 번역 서비스'를 만드는 개발 팀에서 이 서비스를 사용할 사용자들을 위해 기술문서를 만든다는 컨셉으로 시작합니다. 만약에 내가 팀원으로서 기술문서를 작성해야 하는 입장이라고 생각하고 읽었더니 더욱 몰입해서 볼 수 있었습니다.

또 책의 저자분들이 테크니컬 라이팅을 하시는 분들이다 보니 이 책의 내용도 엄청 잘 읽히는 것도 있었습니다.

 

책의 목차는 아래와 같은데요. 사실은 기술문서를 작성하는 순서도 아래와 같습니다.

1. 독자 이해하기

2. 문서화 계획하기

3. 문서 초안 만들기

4. 문서 편집하기

5. 샘플 코드 통합하기

6. 시각적 콘텐츠 추가하기

7. 문서 배포하기

8. 피드백 수집하고 통합하기

9. 문서 품질 측정하기

10. 문서 구조화하기

11. 문서 유지 관리 및 지원 중단하기

부록 A, B, C

 

각 챕터마다 설명이 친절하게 잘 되어있고 예시도 많아서 하나씩 따라해보는 재미가 있을 것 같았습니다.

제가 인상 깊었던 내용을 간단하게 정리해보면 좋을 것 같습니다.

 

 

 

'문서 작성에서 어려운 일 중 하나는 빈 문서를 대면하는 것입니다. ...(중략) 이 어려움을 인정하는 것이 문제를 풀어나가는 첫 번째 걸음입니다'

- 우리가 글을 쓰는 것을 어려워 하는 이유는 처음부터 글을 완벽하게 써야할 것 같다는 부담을 느끼고 시작을 하는 것 조차 두려움을 느끼기 때문이라고 생각합니다. 이 책에서는 이것은 원래 어려운 일이 맞고, 처음부터 완벽하게 작성할 필요가 없다. 초안을 먼저 작성하고, 쓰고 싶은 순서대로 쓰고 여러번 쓰고 피드백을 반영해가면서 결과물을 만들어내자는 작성 방식을 소개하고 있습니다.

 

'기술 문서에는 대상 독자가 반드시 있어야 하고 독자의 눈높이에 맞게 기술 수준을 풀어서 설명해야 하는 거죠. 독자가 알고 싶어 하는 바를 명확하고 간결하고 일관되게 전달하는 것이 매우 중요합니다.'

- 부록A에 보면 국내 테크니컬 라이터분들의 인터뷰를 확인할 수 있는데요. 모든 분들께서 공통적으로 중요하게 여기는 내용은 독자를 파악하고, 독자의 니즈를 충족시키는 글을 작성해야 한다는 것입니다. 이를 통해 기술 문서를 통해 전달해야 하는 가장 최우선의 가치가 무엇인지 알 수 있었습니다.

 

'픽사에서는 창의적이거나 기술적인 작업에 대한 피드백을 제공할 때 플러싱이라는 규칙을 따라야 하며, 이 규칙은 다음과 같습니다. 건설적인 제안을 덧붙이는 경우에만 아이디어를 비판할 수 있습니다.

- 제가 NEXTSTEP 에서 글쓰기 워크숍 교육을 들었을 때도 경험했던 내용이었는데요. 다른 사람의 의견이 아쉽다고 말을 하려면 어떻게 개선해야할지에 대한 내용도 함께 얘기를 해줘야 한다는 것입니다. 누군가의 의견에 '그건 좀 별로인데요?'가 아니라 '그건 이러한 측면에서 조금 아쉬운 부분이 있는 것 같아요. 혹시 이렇게 해보면 어떨까요? 그러면 아쉬운 부분을 해소할 수 있을 것 같아요!'와 같이 제안을 해줘야 한다는 것이었습니다.

 

이 외에도 마음에 와닿고 기술 문서를 작성하는데 있어 도움이 되는 내용들이 책의 시작부터 끝까지 듬뿍 담겨있는데요.

문서화에 관심이 많고, 문서를 작성해야 하는 상황이라면 이 책을 통해 두려움을 없애고 좋은 문서를 작성하실 수 있다고 생각합니다.

 

"한빛미디어 <나는 리뷰어다> 활동을 위해서 책을 제공받아 작성된 서평입니다."

개발자이든, PM이든, 개발과 관련된 모두는 문서를 작성하는 능력이 필요합니다.

그리고 문서를 잘 작성한다면 타인 뿐만 아니라 미래의 자신에게도 큰 도움이 될 겁니다.

지금 바쁜 프로젝트만 마감하면 한번 각 잡고 읽어봐야겠네요.

1234.jpg

 

문서화는 굉장히 중요하다고 생각한다. 신입 개발자가 입사했을 때, 모든 정보를 습득할 수 있게 하며 개발 과정을 엿볼 수 있게한다. 대표적으로 마이크로소프트 문서를 보자. 비쥬얼 스튜디오에서 발생한 모든 오류에 대한 정보가 이미 문서화되어있다. 심지어 개발을 위한 기초 가이드 문서도 잘 작성되어있다. 물론 이 문서화하는 과정은 굉장히 번거롭고 귀찮은 작업이다. 가끔보면 이 문서화를 왜 해야되나 라는 생각이 들 정도이다. 그러나 개발자라고 칭한다면 문서화는 해야한다.

 

부제로는 테크니컬 라이터들을 위한 기술 문서 작성 가이드북이지만 대부분의 개발자들한테도 통용되는 얘기라고 생각한다. 개발자들은 단순히 알고리즘을 구현하고 코드만 작성하는 것이 아니다. 기획에도 참여하여 어떠한 부분이 가능하고 안되는지 토론하고, 개발 과정을 문서화하며 작성한 코드가 어떻게 동작하는지 주석과 UML과 같은 순서도도 작성해야한다.

 

이 책은 '강아지 음성 번역 서비스'라는 가상의 Corg.ly 서비를 만드는 개발 팀의 스토리를 따라가며 개발 문서가 어떤 단계를 거쳐 작성되는가를 살펴본다. 테크니컬 라이팅은 기술 정보를 가공하여 독자가 소화하기에 적합한 문서로 만드는 일이다.물론 이 작업은 제품의 성격에 따라 천차만별로 달라진다. 그렇기 때문에 책에서는 가상의 서비스를 예시를 들었지만 포괄적인 개념에서 설명해주고 있다.

 

어찌되었든 기술 문서의 핵심은 간결하고 명확해야 한다는 것이다. 개발자가 아니여도 해당 제품이 어떠한 방식으로 동작하는지 이 문서가 무엇을 설명하고 있는지 알 수 있어야 한다는 것이다. 그렇다면 간결하고 명확한 문서화를 위한 단계는 어떤식인가는 아래와 같이 서술한다.

 

KakaoTalk_20230527_162704140_01.jpg

 


 

개인적으로 핵심이라 생각하는 챕터는 6과 8,9 이다. 시각적 콘텐츠는 굉장히 중요하다. 아무리 글을 굉장히 잘 썼다고 하더라도 전체 구조를 한번에 보여주는 시각적 자료만 못하다. 시각적 콘텐츠를 만드는 도구는 많지만 사람들이 간과하는 부분이 있다. 바로 회의때 종이 위에 끄적였던 자료만으로도 충분히 훌륭한 시각적 자료가 된다는 것이다.

 

이 책에서 살짝 아쉬운 점이라면 포괄적인 설명을 하기 위해 확실한 예시가 부족하다는 느낌을 받았다. 가상의 서비스를 토대로 스토리텔링 방식으로 서술한건 좋았지만 처음보는 사람에게는 너무 두리뭉실한 느낌이다. 차라리 실제 예를 토대로 각각을 설명해주는 방식은 어땠을까 하는 아쉬움도 있다. 물론 활용하는 방식에 따라 이렇게 포괄적인 방식으로 설명해주는 것이 더욱 좋을 수 있다.

 

여담으로 이번에 e-book으로 처음 신청해보았다. 그러나 이런 기술 서적들은 e-book으로 받기 보다는 실물 책으로 받는 것이 훨씬 읽기도 편한것을 느꼈다. 익숙하지 않아서 보는 것이 불편한 것도 있지만 특정 내용을 보기 위해 빠르게 챕터를 훑는 것이 안되니 답답하였다. 다음부터는 기술 서적은 실물로만 받아야겠다.

 

"한빛미디어 <나는 리뷰어다> 활동을 위해서 책을 제공받아 작성된 서평입니다."

 
 
Docs for Developers 기술 문서 작성 완벽 가이드 - 우아한형제들 카카오 등 국내 테크니컬 라이터 11인 인터뷰 특별 수록
자레드 바티 외 지음, 하성창 옮김 / 한빛미디어 / 2023년 4월
평점 : 
장바구니담기 


 

저자

자레드 바티, 재커리 사라 콜라이센 외 3명

 

#책소개

소프트웨어 개발자를 안내하는 테크니컬 라이팅을 위한 실무 노트
우아한형제들, 카카오, AWS, LINE Plus, 쿠팡, NHN, 데브시스터즈, 넷마블 등 국내 테크니컬 라이터 11인 인터뷰 특별 수록!

이 책은 ‘강아지 음성 번역 서비스’를 만드는 개발 팀의 스토리를 따라가며, 개발 문서를 만드는 과정을 단계별로 배우도록 구성되었습니다.

단계별 예제, 템플릿, 가이드를 통해 이론적인 내용뿐만 아니라 문서를 효과적으로 작성하고 관리하는 방법도 배우게 됩니다.

단계에 맞는 문서화 기술을 배우고, 사용자 니즈 이해부터 문서 작성, 유용한 개발자 문서 배포 및 유지까지 프로젝트 관리와와 소프트웨어 개발 라이프사이클 전체를 한 권에 담아 설명합니다.
또한 부록에는 우아한형제들, LINE Plus, 카카오엔터프라이즈, NHN 클라우드, 넷마블, 데브시스터즈, AWS, 쿠팡에서 활동하는 국내 유명 테크니컬 라이터 11인의 인터뷰가 수록되었습니다.

테크니컬 라이팅이 무엇인지, 업계에서 테크니컬 라이터의 역할에 대해 설명합니다. 이미 테크니컬 라이팅의 세계를 경험한 선배들의 다양한 경험과 이야기를 들을 수 있습니다.

라고 말하더라.

 

 


 

# 이 책의 특징

 

1. 구성

구성은 왠지는 모르겠지만 조금 산만하다.

내용을 이해하려면 집중해야 한다.

또한 구성이 그렇게 읽기 쉽지는 않다.

 

 

2. 기술 위주

당연히 개발자를 위해서 적는 것은 당연하지만

조금 일반적인 글을 쓰고 그 다음 개발자를 위한 글을 쓰는 것도 좋았을 것 같다.

 

 

3. 실제 경험담 위주

당연히 경험이 많은 사람들이 썼기 때문에 정말 잘 쓴 것 처럼 보이지만..이것을 일반인이 읽는다고 했을때도 구성이 비슷해야 잘읽히는가? 는 조금 고민해야 할듯

 

 

 


 

#후기

 

솔직히 다 집중해서 읽진 못했다.

하지만 재밌게 읽은 것은 사실이다.

내가 지금까지 글을 어떻게 썼는지, 어떻게 써야할지 많이 반성을 하게 된다.

아직 이러한 것을 적용해서 글을 쓰지 않았지만

써보려고 한다.

문서 작성 … 애써 외면해본다

개발 자체만큼이나 중요한 부분이 문서 작성이라는 것을 부정하는 개발자는 없다. 하지만 문서를 보고 문서를 작성한 개발자를 탓하고, 나의 동료를 탓하고, 더 나아가 과거에 그 문서를 작성했던 사람이 나 자신이었음을 깨닫고 소위 말하는 현자타임에 빠지는 경우를 자주 경험해봤을 것이다(나만 그런 건 아니지?). 성숙한 개발 조직이 아닐 수록, 이런 경우를 많이 맞닥뜨릴 때가 있다. 소수의머리로는 아는 사실을 마음은 애써 외면하는 걸까?

(1) 가이드라인 없거나, (2) 어떻게 작성해야할 지 막막하거나, (3) 사내에서 잘 작성된 문서라는 기준이 정해져있지 않거나, (4) 중요하다고 인식되지 않아 충분한 시간이 주어지지 않거나 시간을 들여도 인정 받기 어려워서 … 일 것이다. 이 모든 것이 전부 다 해당될 수도 있다.

Docs for Developers

한빛미디어에서 출간된 Docs for Developers 기술 문서 작성 완벽 가이드 는 제목 그대로 기술문서를 “제대로” 작성하기 위한 가이드를 담고 있다. 개인적으로 이 책의 처음 목차를 보았을 때, 내용이 탄탄할 것이라는 기대가 들었고, 실제로 책을 통해 기술 문서를 작성할 때 막막했던 부분들을에 대한 조언을 많이 받을 수 있었다.

Docs for Developer 기술문서 작성 완벽 가이드 (저자: 자레드 바티 외 4인)

Docs for Developer 기술문서 작성 완벽 가이드 (저자: 자레드 바티 외 4인)

내용 훑어보기

기술 문서를 작성하기 위한 첫 발자국부터, 문서의 유지보수와 더 이상 유효하지 않은 문서를 종료하는 단계까지 전체적인 내용을 훑고 있다. 특히 가상의 서비스를 사례로 들어 실제로 문서를 기획하고 구축해나가는 과정을 통해서 내용을 효과적으로 전달하고 있는 것이 이 책의 장점이다.

  1. 독자 이해하기
    • 기술 문서의 사용자를 먼저 파악해봄
      • 사용자 니즈
      • 사용자 패르소나
      • 사용자 여정
  2. 문서화 계획하기
    • 문서의 유형
      • 코드
      • 리드미
      • 시작하기 문서
      • 개념 문서
      • 절차 문서
      • 참조 문서
  3. 문서 초안 만들기
  4. 문서 편집하기
    • 편집 접근법
      • 기술적 정확성 -> 정확한 명명? 혼동을 일으킬만한 용어 은어? 독자가 기대한 결과
      • 완전성 -> Todo, TBD가 채워졌는지? 성공적인 사용을 위한 정보가 다 들어가있는지?
      • 구조 -> 흐름과 분류
      • 명확성/간결성 -> 표현 / 불필요한 부분 / 편향된 언어
    • 편집 프로세스
      • 예) 작성자 검토 -> 동료 검토 -> 기술적 검토
  5. 샘플코드 통합하기
    • 샘플코드의 복잡성을 단계별로 명확하게 나누기
  6. 시각적 콘텐츠 추가하기
    • 스크린샷
    • 다이어그램 (플로우차트, 스윔레인)
    • 비디오 콘텐츠
    • 유지하기
  7. 문서 배포하기
    • 릴리스 프로세스 구축
    • 타임라인 만들기
    • 전달 방식 (매체)
    • 문서가 배포됨을 알리기
  8. 피드백 수집하고 통합하기
    • 피드백 채널
      • 직접 수집
      • 고객지원 업무 중 문제 모니터링
      • 문서의 고객 평가 수집
      • 사용자 설문조사 / 사용자 위원회
    • 후속 조치
  9. 문서 품질 측정하기
    • 기능적 품질 : 이루고자 하는 목표를 달성하는지 (정확한 내용 전달 등등)
    • 구조적 품질 : 얼마나 “잘” 작성되었는지 (명확, 간결 등등)
  10. 문서 구조화 하기
    • 문서는 양이 커짐 … 문서 콘텐츠를 올바르게 구조화 하기
      • 사이트 탐색 구조
      • 랜딩 페이지
      • 탐색 신호 (검색)
  11. 문서 유지 관리 및 지원 중단하기
    • 문서 최신 유지하기
    • 담당자 선정
    • 유지 관리 자동화
    • 문서 삭제

아쉬운 부분

Docs for Developer 에서 약간 아쉬웠던 부분은 번역이었다. 많은 개발 용어들이 영문 표현에 기반을 두고 있는데, 개인적으로는 영어 표기를 어느 정도 그대로 따라가는 것이 추후 내가 책을 통해 얻은 정보와 현업에서 사용되는 용어를 연관시키고 역량을 확장시키는데 도움이 된다고 생각한다. 하지만 번역으로는 쉽게 와닿지 않는 부분이 있어 “원서나 실제 영미권에서는 이 용어를 어떻게 쓰는지” 의문이 들어 중간 중간 추가적으로 찾아봐야 했던 상황이 종종 있었다. (예: 마찰 로그 -> Conflict logging) 출판사 정책 등으로 굳이 개발 용어를 번역 해야한다면, 괄호 또는 주석으로 영문을 함께 표기하는 것이 개발자인 대다수의 독자에게 내용을 전달하는게 더 편리하지 않을까 하는 인상이 들었다.


한빛미디어 <나는 리뷰어다> 활동을 위해서 책을 제공받아 작성된 서평입니다.

 

이 책을 보고 든 생각은 이제는  좋은 글, 도움이 되는 글 쓰는 것 자체도 코드를 작성하고, 구조를 고민하고 프로그래밍을 하는 것 만큼 쉽지 않은 것이다. 라는 생각이 들었다.

 

처음에는 기술관련 개인 기록용으로 시작했던 블로그가 점점 보는 사람들이 미세하게 나마 많아지면서 기술 문서처럼 되었으면 하는 바램이 0.001%(?) 정도 증가하면서 관심가져 보게 된 책이다.

 

"... 이 책의 원서에는 '엔지니어를 위한 테크니컬 라이팅 실무 가이드' 라는 부제가 붙어 있습니다. '테크니컬 라이팅'은 기술 문서를 작성하는 일로, 이 책은 소프트웨어 개발자를 위한 테크니컬 라이팅 안내서라고 할 수 있습니다...."

 

 

 

이 책은 아래의 챕터들을 가지고 있고, 가상의 서비스 Corg.ly 라는 걸 만드는 개발 팀에 대한 이야기로 만들었다고 한다.

 

챕터 1 - 독자 이해하기
챕터 2 - 문서화 계획하기
챕터 3 - 문서 초안 만들기
챕터 4 - 문서 편집하기
챕터 5 - 샘플 코드 통합하기
챕터 6 - 시각적 콘텐츠 추가하기
챕터 7 - 문서 배포하기
챕터 8 - 피드백 수집하고 통합하기
챕터 9 - 문서 품질 수정하기
챕터 10 - 문서 구조화 하기
챕터 11 - 문서 유지 관리 및 지원 중단하기

부록A - 국내 테크니컬 라이팅은 어떨까요?
부록B - 전문가를 고용해야 하는 이유
부록C - 참고 자료

 

그러면서 겪게 되는 과정들에 대한 고민들과, 그런 고민들에 대한 부분들을 세세하게 나눠서 알려준다.

그러면서 테크니컬 라이터라는 전문직업이 회사 마다 있다는것도 알게 되서 신기했다.

 

 

기술 문서를 쓰는 방법, 국내외 테크니컬 라이터분들과의 인터뷰 등을 볼 수 있고, 이런 쪽으로 관심이 있다고 한다면 도움이 될 듯 하다

"...문서의 대상, 목적, 패턴을 정의하는 것으로 시작하세요. 문서의 목표가 문서의 제목에서 드러나야 합니다.. (챕터 3 문서 초안 만들기) 중 일부"

 

테크니컬 라이트에 대해 참고 영상:

https://www.youtube.com/watch?v=95E0EbHo2xQ&ab_channel=%EB%9D%BC%EC%9D%B8%EA%B0%9C%EB%B0%9C%EC%8B%A4%EB%A1%9D 

 

 

 

"한빛미디어 <나는 리뷰어다> 활동을 위해서 책을 제공받아 작성된 서평입니다."

4.jpg

 

개발자를 포함한 소프트웨어 엔지니어들이 가장 힘들어하는 영역중에 하나를 꼽는다면 문서 작성이라고 말할 수 있을 것 같다. 특히 개발자의 경우 일상적인 대화는 문제가 전혀 없는데 작성된 문서를 보면 많은 차이가 생기는 것을 보게 된다. 책에서도 언급이 되지만 문서 작성을 위해 워드나 한글 프로그램을 실행한 후 한동안 멍하게 있는 경우도 종종 보곤 한다. 그만큼 문서의 작성이 쉽지 않다는 것을 보여주는 것 같다.

 

이 책은 소프트웨어 엔지니어가 어려워하는 문서 작성에 대한 단계별 절차를 잘 설명한다. 실제 업무 환경과 유사하게 강아지 음성 번역 서비스를 개발하는 개발팀을 통해 사용자 파악, 요구사항 분석, 절차 등을 실제와 유사하게 보여준다. 특히 개략적인 설명에 끝나지 않고 필요한 요소와 이에 대한 템플릿을 같이 제시함으로 실제로 문서 작성을 시작하기 어려웠던 사람들에게 실용적인 가이드를 제시해 주고 있다.

 

이 책은 크게 11개의 장으로 구성되어 있다. 1장 독자 이해하기에서는 문서화를 위해 필요한 사용자 공감의 중요성에 대해 언급하며, 인터뷰, 개발자 설문조사, 고객 지원 문제 검토와 같은 사용자 조사 및 도구를 사용할 수 있음을 설명한다. 특히 사용자의 경험에 대한 마찰 로그를 문서화하고 이를 통해 사용자와 공감하는 것이 중요하다는 것을 잘 보여준다. 2장 문서화 계획하기에서는 만들어야하는 콘텐츠 및 컨텐츠 유형을 문서 작성에 앞서 설명하는 것이다. 문서화 계획은 사용자가 필요로 하는 콘텐츠의 유연한 밑그림 역할을 하면서 소프트웨어 엔지니어가 가장 중요한 문서를 작성하는데 집중할 수 있도록 해 준다.

 

3장 문서 초안 만들기에서는 편안하고 친숙한 문서 작성 도구를 선택하여 성공적인 글쓰기 준비를 도와주며, 4장 문서 편집하기에서는 작성된 초안을 기반으로 정확성,  완결성, 구조, 간결성, 명확성을 높이는 방향으로 진행되며 특히 동료 검토 및 피드백의 중요성에 대해 잘 알 수 있다. 이어지는 모든 장에서도 각 단계에 맞는 적절한 문서 단계에 대해 설명한다. 특히 10장 문서 구조화하기와 11장 문서 유지 관리 및 지원 중단하기는 문서를 작성한 후 관리를 위해 필요한 여러 단계 및 계획에 대해 잘 설명하고 있다.

 

문서 작성에 대해 어려움을 느끼거나 거부감을 느끼는 사람도 많은 것 같다. 이는 문서 작성 자체에 대한 어려움보다 제대로된 문서 작성 경험 부족과 제대로 된 절차를 잘 알지 못해 생기는 경우가 더 많다는 생각이 든다. 문서 작성에 어려움을 느끼고 있는 소프트웨어 엔지니어라면 이 책을 통해 문서 울렁증에서 벗어날 수 있는 계기가 될 수 있을 것 같다.

 

"한빛미디어 <나는 리뷰어다> 활동을 위해서 책을 제공받아 작성된 서평입니다."

개발자를 위한 문서는 개발자 경험을 향상시키고 제품의 채택률을 높이며 고객 지원 비용을 낮춰준다고 한다. 또한 장기적으로는 제품의 평판을 높이고 경쟁 우위를 제공하여 사업의 성공에 중요한 역할을 한다고 한다. 개발자 문서를 잘 만들고 관리하는 방법은 무엇일까? 이 책에서는 문서화 하기 전 독자 이해하기, 문서화 계획하기, 초안 만들기, 편집 하기, 샘플 코드 통합하기, 시각적 콘텐츠 추가하기, 문서 배포하기, 피드백 수집하고 통합하기, 문서 품질 측정하기, 문서 구조화 하기, 문서 유지 관리 및 지원 중단하기 까지 개발자 문서를 완벽하게 만들기 위한 가이드를 End-to-End로 제공한다. 코드 자체가 잘 작성된다면 그 자체로 문서화가 된다는데, 복잡성과 규모가 일정 수준 이상인 프로젝트에서는 코드 레벨에서 이해를 시작하는게 아니라 다른 사람들이 빨리 이해할 수 있도록 사람이 읽을 수 있는 형태의 문서가 훨씬 더 효과적이다. 

 

먼저 문서화 하기 전에 사용자가 누구인지 이해하는 과정이 필요하다. 예를 들면 개발자, 프로덕트 매니저 또는 시스템 관리자와 같은 역할에 따라 사용자를 정의할 수 있다. 이러한 사용자의 역할에 따라 고려해야할 점도 달라진다. 예를 들면 사용자가 개발자인경우 보유 기술, 사용 프로그래밍 언어, 개발 환경, 사용 운영 체제, 팀 내 역할을 고려하여 카테고리를 만들어야한다. 그 다음에 사용자의 니즈가 무엇인지에 대해서 사용자 조사를 실시하여 독자에 대해 깊이있게 이해하는 과정을 거친다. 

 

그 다음 사용자에게 가장 중요한 유즈케이스를 파악하여 그들의 니즈를 해결하는 콘텐츠 유형으로 문서화 계획을 세운다. 코드 주석만으로는 사용자가 시스템을 이해하기에 충분하지 않기 때문에 README를 작성하는 것이 좋다. README는 Mark Down 형태로 작성하며, 간결하고 유익하며, 정확하게 최신 정보를 담고 있어야 한다. README에 담겨야할 내용 중 가장 중요한건 How-to 가이드다. 여기에 필수 조건을 포함시켜야하며, 참조 문서나 API 관련된 정보를 기입할 수 있다. 그 다음 문서의 제목에는 문서를 읽는 목적을 요약해두어야하며, 목표를 한가지로만 제한하는 것이 좋다. 목표가 여러개라면 여러 개의 문서가 필요하다. 

 

이렇게 개발자 문서를 작성하는데 있어서 제일 중요한 것은 '독자'를 최우선으로 해야한다는 것이다. 작성하는 문서가 독자들에게 최대한 이해하기 쉬운 내용인지에 대한 통찰력을 기르는 것도 중요하다. 이렇게 하면 독자 누구나 이해하기 쉬울 수 있는 문서를 작성할 수 있다고 한다. 

 

책의 마지막 부분에는 실제 업계에서 테크니컬 라이터로 활동하고 계시는 11명인의 인터뷰가 수록되어있다. 그 중 가장 기억에 남는 말은 기술 문서의 작성 목적은 서로 다른 기술 스택을 보유한 개발자 모두가 협업의 본질을 이해하고, 해당 업무가 처음이더라도 원활하게 일할 수 있는 훌륭한 가이드나 매뉴얼을 남기는 것이라고 한다. 

 

한빛미디어에서 출간된 기술 문서 작성 완벽 가이드라는 책은 테크니컬 라이터라는 직업에 대해 관심을 갖고 있거나, 개발자 문서를 더 잘 쓰고 싶은 사람, 개발자 문서를 이제 막 써야되는 사람에게 모두 추천하고 싶은 책이다. 

 

“한빛미디어 <나는 리뷰어다> 활동을 위해서 책을 제공받아 작성된 서평입니다."

개발 감자 신입이지만 생각보다 개발자도 문서를 작성해야할 일이 많다. 사용자 가이드, API 명세서, URL 리스트 등등..

개발자 - 개발자의 문서 뿐 아니라 개발자 - 사용자 간의 문서또한 작업할 일이 생기는데, 그 시점에 이 책을 서평할 기회를 갖게되었다.

 

갑자기 문서를 만들어야한다는 업무가 주어졌는데 레퍼런스가 없는 상황에서 막막하기만 했다. 하지만 기술 문서 작성 완벽 가이드 책 덕분에 어디서 부터 시작해야할 지 진입점을 찾을 수 있었다. 뭔가 만들어야 한다 라는 생각에 빠져있던 나의 초점을 문서를 건넬 대상 이해부터 시작해야한다고 시선을 돌려준 덕분에 첫 단추를 잘 꿸 수 있었다.

 

뭔가를 만들기에 앞서 사용자에게 제시할 수 있는 목표를 정하고, 사용자를 이해하고, 사용자의 니즈를 파악한 후 작업을 시작하니 더 편하게 문서의 윤곽을 잡아갈 수 있었다. 무작정 뭔가 만들어야 한다는 막막함에서 벗어날 수 있게 해주었다. 이후 책의 목차를 따라 초안을 만들고 편집하고 검수받고 수정하고 통합하는 과정을 거쳐가면서 팀장님이 원하던 문서규격을 만들었다. 그리고 그 만든 문서규격를 따라 다른 프로젝트들에도 사용하기로 했다. 

 

처음 맡는 업무에 막막했지만 기막힌 타이밍에 만난 이 책 덕분에 기간내에 좋은 결과를 받게 되었다. :) 햅삐 

마지막부분에 테크니컬 라이터분들의 실제 업무 경험 인터뷰까지 들어있어서 도움이 많이됐다.

 

"한빛미디어 <나는 리뷰어다> 활동을 위해서 책을 제공받아 작성된 서평입니다."

개발자 그룹에서 문서를 쓴다고 하면 보통 '기획자'의 일이라고 치부하기 쉽다. 하지만 기획자가 아니라도 생각보다 '문서'를 쓸 일은 빈번하게 발생한다. 뭐 기획자라고 모두 글을 잘 쓰고 문서를 잘 만드는 것은 아니다. 우리는 모두 '독자'가 누군지를 두고 문서를 써야 하고, 독자는 '지금 하고 있는 것을 자주 안 해서 그때 다시 하려니 전혀 기억이 안 나는' 미래의 나일 수도 있고, '내가 지금 하고 있는 일을 인계받아서 이어서 진행하게 될' 미래의 부사수일 수도 있다. 또는 '내가 개발한 소프트웨어가 제대로 작동하는지 테스트해줄' 테스터 일 수도 있고. 

 

20230505_013825.jpg

 

도서 'Docs for Developers'. '기술 문서 작성 완벽 가이드'는 문서랑은 담을 쌓고 지낼 개발자에게 이름 그대로 완벽한 가이드가 되어 줄 책이다. 

 

이 책을 통해 자신의 경험과 노하우를 전해 준 테크니컬 라이터 한 명이 말하길, 기술 문서의 작성 목적은 서로 다른 기술 스택을 보유한 개발자 모두가 협업의 본질을 이해하고, 해당 업무가 처음이더라도 원활하게 일할 수 있는 훌륭한 가이드나 매뉴얼을 남기는 것이라고 했다. 실제로 나는 주로 프로젝트에 새로운 담당 기획자가 오더라도 바로 실무에 적응할 수 있게, 가이드 문서나 매뉴얼 작업을 수시로 하고 최신화를 하고 있다. 물론 안타깝게도 이건 내 이야기이고 보통은 자신이 너무나 익숙하게 담당하고 있는 일들이라 별도의 매뉴얼이나 가이드를 만들 생각을 하지 않는다. 일할 시간도 부족한데 시간을 쪼개서 문서까지 만들기는 번거롭고 우선순위에서 밀리니까.

 

하지만 잘 만든 가이드 문서는 이후에 번거롭게 '교육'이라는 명목으로 업무를 가르칠 필요를 줄여주고, 담당자가 바뀌거나 내가 부득이하게 부재하게 되더라도 다른 사람이 원활하게 그 자리에 적응할 수 있게 해준다. 이 맛에 매뉴얼을 만든다. (나 없으면 회사가 안 돌아간다는 것은 어디까지나 직원의 착각일 뿐이고, 실제로는 거의 그렇지 않다.)

 

20230505_013829.jpg

 

나는 라이브 서비스의 기획자다. 반복적으로 진행되는 업무들이 많은데 그 텀이 주 단위일 때도 있고 월 단위 일 때도 있고 때론 연 단위일 때도 있다. 6개월 이상으로 터울이 벌어지면 다시 그 업무를 해야 할 때가 되었을 때, 뭐부터 해야 하더라 멍~ 하게 될 때가 있다. 그래서 나는 업무툴의 매뉴얼부터 시작해서 업데이트 프로세스를 문서로 작성하고 그걸 템플릿 화해서 업무에 적용했다. 매달 반복되는 업무에 누락되는 부분이 없고 라이브 서비스에서 오류가 생기는 일도 거의 없게 되었다. 무엇보다 좋았던 부분은 이 템플릿을 다른 프로젝트에 적용할 수 있었고, 프로젝트 담당자가 바뀌었을 때 신규 담당자도 템플릿과 매뉴얼, 가이드를 통해 보다 빠르게 업무에 적응할 수 있었다.

 

혹자는 내가 매뉴얼과 가이드 문서를 작성하라고 했을 때, 업무할 시간도 없는데 번거롭게 왜 그런 일까지 해야 하는가라고 반문했지만, 시간이 지나 결과를 보면 복잡도가 요구되는 업데이트에서 가이드 문서가 있는 것과 없는 것은 라이브 결과에 큰 영향을 미친다. (예를 들면 라이브되면 안 되는 아이템이 실수로 라이브 되거나, 아이템이나 스킬 수치가 잘못 패치 된다거나, 리소스가 누락된다거나 하는 것 들 말이다.)

 

그뿐인가.

기획자가 아니더라도, 프로그래머도 본인이 분석 및 R&D 한 결과를 말로만 전달할 수는 없다. 간단한 것은 물론 가능하겠다만, 문서로써 기록을 남기고 그 문서를 보는 독자(예를 들면 기획자라든가)가 이해할 수 있고 재활용할 수 있는 지식을 남겨두면, 후에 같은 일을 또 하게 되는 일도 막을 수 있고 다른 누군가가 그것에 대해 물어보았을 때 잘 정리된 문서의 링크를 전달해 주면 그만인 것이다.

 

생각하기에 따라 번거롭지만 업무 효율과 사후 관리를 매우 편하게 하는 기술 문서 작성. 그리고 이 책은 문서랑은 도통 친하지 않은 개발자들에게 의미 있고 가치 있고 전달력 있는 문서를 작성하는 방법을 알려준다.

 

그 예전에 어디 컨퍼런스 강의에서 '프로그래머에게 사랑받는 기획서 작성 방법' 뭐 이 비슷한 내용이 있었는데, 기획자도 봐두면 아주 도움이 되는 책이다.

 

이 책은 'Corg.ly'라는 가상의 프로젝트를 통해 출시 전부터 출시 후까지를 다루며 개발 문서를 어떻게 작성해 나가는지 챕터별로 그 과정을 다룬다. 활용하기에 따라 정말 다양하게 응용이 가능한 내용으로 개인적으로는 신입 기획자한테도 추천하고 싶은 책이다. 사업팀 신입이 봐도 좋을 것 같다. 어떻게 이런 책이 이제야 나온 것일까. 

 

책을 읽고 나서 회사에 두고 신입들 보게 하려고 회사에 구매 요청도 해뒀다.ㅋㅋㅋㅋ

 

한빛미디어 <나는 리뷰어다> 활동을 위해서 책을 제공받아 작성된 서평입니다.

한빛미디어 <나는 리뷰어다> 활동을 위해서 책을 제공받아 작성된 서평입니다.
최근 개발자 취업과 관련하여 몇 회사에서는 자소서 보다 문서를 중요시 한다는 것을 들었습니다.
포폴과 관련하여 README, 명세서 등을 주로 본다는 것 입니다.
개발자에게 개발 능력 만큼 문서 작성 능력도 요구한다는 것을 느꼈습니다.
문서 작성을 아무리 못하더라도 이 책을 참고한다면 많은 도움이 됩니다.
대충 읽어도 이해할 수 있을 정도로 쉽게 서술하고 있고 예시도 있어서 따라하기 편했습니다.
급할 땐 매 챕터의 요약만 읽거나, 개발과정 전반에 걸쳐 작성되는 문서에 대해 다루고 있기 때문에 현재 과정에 해당하는 챕터만 봐도 될 것 같습니다.

굳이 테크니컬 라이터가 아니더라도 실제로 업무와 관련된 각종 다양한 문서를 작성하는 포지션에 있는 사람이라면 누구나 읽어 볼 가치가 충분한 책이라 생각된다. IT관련자라면 더욱 도움이 되겠지만 비관련자라도 작업자 간에 정보공유를 위한 문서를 작성하고 있거나 이제부터라도 작성해야 하는 이라면 누구나 대상이 될 수 있는 책이다.

 

# 기술 문서 작성

혼자 일을 할 경우, 다음에 일하게 될 직위, 경력등 불특정된 후임을 위한 문서를 작성해 두는 편이다.

팀으로 일할 경우 선행 작업으로 알게 된 각종 내용, 사전지식 등을 공유하기 위한 작업자들을 위한 배포문서를 작업할 때도 유용한 내용들로 이루어져 있다.

지금까지의 경험상 대체로 이러한 문서를 접하는 작업자들은 읽고 지나치면서 제대로 된 피드백을 제공하지 않는 경향이 있어서 문서의 질을 높이는 것이 힘든 편이다. 문서의 중요성은 누구나 알지만, 문서를 만드는데 들여야 하는 절대적 시간에 대해서는 누구나 시간을 할애하는데 인색한 편이다. 말하기는 쉬워도 실제로 손을 움직이는 건 어려우니까.

그럼에도 문서를 솔선해서 작업하는 이유는 나름의 업무를 대하는 자세, 혹은 개인적인 폴리시라고 생각한다. 프로젝트 특성상 대부분 오픈되는 문서가 아니기 때문에 대외적인 평가를 받기도 힘들고 일부는 있는지도 모르고 관심 없는 문서로 취급받지만 어느 순간 미약하게나마 누군가에게 도움이 된다면 좋을 것 같다.

 

# Docs for Developers 기술 문서 작성 완벽 가이드

문서를 작성하는데 걸리는 시간은 상당한 시간을 요하고 있지만 일반적으로 문서가 가지는 중요성에 대해서는 약간 간과되고 있는 경향이 없잖아 있다.

경험상 다들 귀찮은 작업이고 일반적으로 프로젝트의 종료시점에 필요한 산출물이나 요청에 의한 작업, 후임이나 동료를 위한 가이드 형식의 짤막한 문장으로 이루어진 Readme가 일반적인 문서 형식이다.

책에서 다루고 있는 기술문서의 개요, 필요성, 바른 작성 및 운용방법 등 읽을거리가 풍부해서 읽는 재미가 있었다. 글을 쓰는 작업을 좋아하거나 누군가에게 도움을 주고 싶거나 바른 문서를 작업하려는 목표가 있거나 정리정돈을 좋아하는 사람이라면 읽어 보면 어떨까 생각된다.

짤막한 정보라도 없는 것보다는 있는 것이 문서를 작성한 당사자가 없더라도 프로젝트를 이어받아 작업하는 누군가에게 기본적으로 인지하고 있어야 하는 작업당시의 정보를 남기는 건 도움이 된다는 것을 알고 있기에 가급적 업무가 바쁘더라도 문서를 작성해서 정리해 두려는 개인적인 행동이 틀리지 않았다는 것을 책을 읽으며 은연중에 느낄 수 있었다. 어디까지나 자기만족이긴 하지만.

 

# 마무리

지금 당장 진행중인 프로젝트에 업무와 관련된 가이드 문서가 없다면 책을 통해 알게 된 10분의 1정도의 지식만 활용해서최소한의 규칙과 방법을 만들어서 공유해 보길 바란다. 주변의 평가가 달라질 거라 생각된다. 일부는 고마워하고 일부는 쓸데없는 짓을 했다고 하겠지만 후자의 경우는 앞으로도 굳이 상종할 필요는 없는 부류라 생각해도 좋을 것 같다.

 

한빛미디어 <나는 리뷰어다> 활동을 위해서 책을 제공받아 작성된 서평입니다.

 

 

Docs_for_Developers.jpg

학습이 아닌 경험으로 알게 된 내용을 잘 정리하여 풀어놓은 듯한 느낌을 받습니다.

너무 와닿는 내용들이라 알려준 대로 따라가기만 하면 좋은 문서를 만들 수 있을 것 같습니다.

하지만, 반드시 모든 단계를 따라갈 필요는 없다는 생각도 듭니다. 책에서 문장으로 표현하지는 않았지만 읽으면서 자연스럽게 알 수 있습니다.

무엇보다 문서를 만드는 게 먼저입니다. 책에 나오는 얘기이기도 합니다만, 기능이 구조보다 우선해야 하기 때문입니다.

좋은 문서라면 나오기까지 걸맞은 단계를 거쳤을 가능성이 큽니다. 그렇다고 해서 문서를 만들기 위한 프로세스에 너무 매달리면 프로세스에 묶여 문서가 나오지 않는 불상사가 생길 수 있기 때문입니다.

 

 

의견을 들어야 한다

 

지식의 저주로 시작하여 내용을 풀어나가기 시작합니다.

첫 부분에 지식의 저주가 등장하는 게 이 책이 무엇을 얘기하고 싶은 건지 한마디로 알려준다고 생각합니다.

같은 문장을 보더라도 사람마다 그리는 이미지, 이해하는 정도가 모두 다릅니다. 그렇기에 매 단계마다 서로가 이해하는 바를 조율할 필요가 있습니다.

처음부터 끝까지 모든 단원에 의견을 들어야 하는 순간이 있습니다.

 

 

혼자가 아니다

 

홀로 존재하는 문서는 있을 수 없습니다. 더욱이 기술 문서는 하나로 모든 것을 설명할 수 없습니다.

관련 문서 가운데 자기 위치가 어디이고 어디로 이어져야 하는지 알려야 합니다.

그렇지 않다면 독자가 읽을수록 헤매게 될 가능성이 다분한 분야이기 때문입니다.

독자가 원하는 정보에 쉽게 접근할 수 있도록 잘 짜여야 합니다. 언제든지 쉽게 정확한 길을 볼 수 있어야 합니다.

혼자가 아니기에 든든하지만, 오합지졸이 되어서는 안 된다고 얘기합니다.

 

 

수명이 있다

 

설명하는 내용에 따라 계속 업데이트해야 합니다. 당연하다고 알고 있지만 실행하기는 만만치 않습니다.

맞지 않는 문서는 없느니만 못합니다. 시간 낭비부터 시작하여 오작동까지 다양한 문제를 일으킬 수 있습니다.

가장 치명적인 건 신뢰를 무너뜨린다는 겁니다.

문서가 사람과 기술을 이어주는 역할을 하는 것처럼 보이지만, 결국은 사람과 사람을 연결합니다.

그렇기에 문서로 이어지는 암묵적인 신뢰가 무너져서는 안 됩니다.

만들고 있는 문서가 어떤 문서인지 항상 명심해야 합니다. 영원히 남을 작품을 만드는 게 아닙니다. 영원히 남아서도 안되고요.

역할에 충실해야 하며, 역할을 다하는 순간 사라져야 하는 문서임을 잊지 말아야 합니다.

 

 

동영상은 문서만큼 효율적이지 않다고 생각합니다.

필요한 부분을 찾기도 어렵고, 원하는 내용이 나오기까지 계속 기다려야 합니다. 이렇게 기다리다 잠드는 경우도 허다하고요. 그렇기에 잘 만들어진 문서를 만나면 핵심부터 살펴볼 수 있기에 만든 이에게 고마울 따름입니다.

 

책을 읽으면 읽을수록 사람을 더 생각하게 됩니다.

문서를 만드는 사람, 관리하는 사람, 읽는 사람. 문서가 널리 알려졌으면 하는 마음으로 소문내는 사람까지.

 

 

"한빛미디어 <나는 리뷰어다> 활동을 위해서 책을 제공받아 작성된 서평입니다."

 당시에는 이 깃헙 레포를 엄청난 레포로 만들어야겠다는 좀 원대한 꿈도 가지고 있었는데, 리비전 때나 지금이나 코드 하나하나에 신경쓸 여유가 없어서 손을 놓고 있긴 하다. 사실, 또 내가 연구를 하는 사람이지 개발을 중점적으로 훈련한 사람도 아니기도 해서 코드도 아마 그리 전문적이지는 않을 것이다. GUI 같은 경우도 사실 정말 너무나 맛보기 수준으로 만들었는데 가끔 사람들이 GUI만 써보고 왜 안되냐고 물어보는 경우도 많은 것을 보면, 좀 더 신경을 쓰긴 해야할 것 같은데 못하고 있다. 

 

 

그러던 와중 이 책을 받았는데, 개발자들을 위한 책인 것 같다. 쌩 개발자들 사이에서는 저 문서화라는 것이 매우 중요하다고 하는데, 나도 어느 정도 관심만 가지고 들어보기만 했을 뿐 자세히는 잘 모른다.

 

 

저자 목록을 보니까, 구글, 리눅스, 마이크로스프트 등 여러 거대한 소프트웨어 회사에서 개발자로 일하신 분들이 함께 쓴 책인 것 같다. 보니까, 테크니컬 라이터라는 직책이 있는 것 같다. 생각해보면, 대학원에서 만드는 하나의 레포지토리도 가끔 너무 복잡해서 서로 이해를 못하는 경우가 있는데, 거대한 회사에서 만드는 큰 서비스 이런 것은 엄청나게 복잡할 것 같긴 하다. 사실, 코드를 좀 짜본 사람이면 알겠지만, 남의 코드 이해하는 게 세상에서 제일 어려운 것이라는 데에 많이 동의할 것이다. 때문에 저런 회사에서 코드를 짜는 것에 언어의 문법마냥 어느 정도 규정을 정하고 서로 이해할 수 있도록 설명서를 만드는 것이 굉장히 중요할 것 같다. 특히, 개발자 한 명이 혼자 코드를 짜는 것이 아니라 여러 명이 짜는 것이기도 하고, 사실 저런 회사에서는 개발자들이 쉽게 갈아끼워지기 때문일수도.. 있겠다는 생각을 해본다. 

 

 

 

책의 추천사에도 여러 유명한 회사들의 테크니컬 라이터들이 글을 남겨놓았다. 당연하지만, 매우 권한다는 것이 주를 이루었다.

 

 

 

모든 발표나, 글들이 그렇듯이, 청자를 이해하는 것이 참 중요하다. 이 책에서도 그것부터 시작한다. 

사실 코딩을 하기는 하지만, 개발이라는 것을 잘 모르는 사람으로 이 책을 읽어보는 것이긴 한데, 전체적인 목차를 봤을 때 좋은 목차로 자세하게 내용을 다루는 것 같다는 느낌을 받았다. 아마 개발 직군으로 면접 보거나 일하게 되면 이 책을 읽어보면 좋을 것 같긴 하다.

 

 

 

그리고 보니까 corgly라는 이 분야에서 쓰는 툴이 있는 것 같은데, 코기라는 강아지마냥 귀여운 캐릭터를 만들어놔서 한 섹션의 시작마다 귀여운 그림을 넣어놨는데 은근 보는 맛이 있다. 보면 컴공쪽 애들이 은근히 저런 캐릭터나 귀여운 것을 좋아하는 것 같다. 물론 다 이상한 컴공쪽 애를 가져와서 캐릭터화 시켜야 한다.


전반적으로 읽어봤을 때, 대충 어떤 식으로 라이팅을 해야하는 것인지 감을 잡을 수 있었다. 나에게 바로 도움은 안되더라도 좀 더 사용자 친화적으로 내 코드들을 설명할 수 있는 글을 쓸 수 있을 것 같다.

"한빛미디어 <나는 리뷰어다> 활동을 위해서 책을 제공받아 작성된 서평입니다."

정답은 없지만 오답은 있다는 격언은 기술 문서에도 꽤나 어울립니다. 완벽한 개발 문서는 없지만, 있는 것에 의의를 둔 문서가 너무 많습니다. 경우에 따라선 코드 작성보다 문서 작성에 더 큰 시간 투자가 필요하거, 유지 보수도 어려울 때가 많습니다. 그래서 코드만 잘 쓰면 굳이 문서가 필요 없이 코드만 읽으면 된다는 입장, 주석은 최소화해서 간결하게 적자 등 개발자 진영에선 개발 문서의 호혜를 입으면서 그렇게 호의적인 태도는 아닙니다.

구 MicroSoft Developer Network(MSDN), 현 Microsoft Docs는 관리가 정말 잘 되고 있는 개발 문서지만 때때로 스펙 변경이 문서에 반영되는 딜레이가 발생 하는 등 개발 문서 관리에 어려움을 개발 문서를 찾아 읽는 매 순간 경험하는 것이 개발자들의 현실이라고 생각합니다.

더불어 가장 큰 이유는 완벽한 개발 문서는 없지만, 너무 많은 오답 문서 때문에 고통 받은 경험과 개발 문서 작성에 대한 체계적인 교육, 자료 부족이라고 생각합니다. 그래서 이 책은 오답을 최대한 줄일 수 있는 방법을 알려주고 있습니다.

개발문서에 대한 큰 가이드를 첫장에서 제시하고 각장을 거쳐 글을 완성도 있게 채워나가는 작업을 합니다. 모든 개발문서가 똑같이 작성될 수는 없습니다. 하지만 기본적으로 고려해야 할 사항은 같습니다. 코드도 상황에 맞춰 적절히 맞추듯 개발문서도 고려사항에 맞춰 기본기를 활욜 할 수 있어야 합니다. 책의 모든 과정을 착실히 수행해도 최상의 글은 나오지 않을 수 있습니다. 하지만 착실한 오답노트의 역할을 해줄 수 있는 책입니다.


한빛미디어 2023 도서 서평단 "나는 리뷰어다"의 일원으로 도서를 제공받아 작성한 리뷰입니다.

한빛미디어 <나는 리뷰어다> 활동을 위해서 책을 제공받아 작성된 서평입니다.

테크니컬 라이터로서의 역할과 기술 문서 작성 방법에 대한 상세 가이드를 제공합니다.

DocsforDevelopers.jpg

 


[주요 용어]

테크니컬 라이터:

  1. 일반인들에게 낯설고 어려운 기술 이야기를 사용자가 쉽게 이해할 수 있는 콘텐츠로 번역하는 직업(SK),
  2. 개발자 중심의 기술 관련 용어나 설명을 독자가 쉽게 이해할 수 있도록 콘텐츠를 가공, 배포, 관리하며, 프로젝트 초기 단계부터 철저한 문서화 작업을 계획하고 수행(Kakao),
  3. 전문적인 정보를 전달해주는 역할을 한다. 어떤 시설이나 장비에 대한 정보를 여러 사람에게 전달해주는 역할이다. 그 정보는 다양한 매체를 통해 다른 사람들에게 전달된다. 테크니컬 라이터는 다양한 매체(전자, 인쇄, 음성, 영상 등)를 통해 컨텐츠를 개발(Wiki)

 

[개요]

기술 문서를 포함 누군가에게 정보를 제공하기 위한 작업을 할 때 우선 정의와 목적을 분명히 해야 한다.

만들 문서에 대한 최소한의 양식이 제공되면 초안 작성과 문서 완성에 도움이 된다.

만든 문서를 이용하는 사람에게 도움이 되고, 필요한 경우 피드백 반영하고 여러 사람이 문서에 대한 편집 권한을 부여하는 등 지속성을 유지할 수 있는 방안도 제시되어야 한다.

기술 문서로서 좋은 샘플 코드들이 포함되어 실제 동작에 대한 설명이 가능해야 한다.

활용 가능한 문서로서 시각적 콘텐츠를 제공하여 이해가능성을 높여야 한다.

작성된 문서는 사용가능하도록 배포되어야 한다.

사용되는 문서는 지속적으로 피드백을 수집할 수 있는 채널을 열고 피드백에 대한 조치를 할 수 있어야 한다.

작성된 문서가 제대로 활용될 수 있는 문서 매트릭을 만들어 문서 품질을 측정할 수 있어야 한다.

문서를 활용하려는 사람이 쉽게 원하는 컨텐츠를 찾을 수 있도록 구조화해야 한다.

문서는 용도가 다할 때까지 최신성을 유지할 수 있도록 해야 한다.

 

20년이 넘도록 다양한 규모(1억~10억~100억~1000억~1조 규모)와 도메인 유형(공공, 유통, 금융, 물류, 교육 등)의 프로젝트에서 최적화된 관리와 다양한 수행 방법론(정보공학, 구조, 빅데이터, AI, 테스트, 이행, 운영 등) 제시하고 관련 방법론에 따른 문서를 수행 단계에 맞도록 테일러링하고 기술 문서를 포함한 수십에서 수백종의 각종 문서들의 템플릿을 제공하고 각 산출물들의 작성 가이드를 제공하여 프로젝트와 공정 단계의 완성을 보장하는 업무를 하고 있다.

Product나 Service, 특정 Solution에 해당하는 기술문서를 작성 및 가이드 하는 경우도 있다.

보잉(Boeing)은 최신 항공기 제작 과정에서 8,000개가 넘는 산업 소프트웨어를 사용했는데, 그중 1,000여 개만 상업 소프트웨어였고, 나머지 7,000여 개는 보잉이 자체 개발한 산업 앱이었다. 보잉은 몇십 년 동안 쌓아온 항공기 설계, 최적화 및 산업 기술과 공정 경험을 7,000여 개의 산업 앱에 담아 보잉만의 핵심 경쟁력을 만들어냈다.

이렇듯 산업 현장에서 테크니털 라이터의 존재가 중요해지고 있다.

추가로 기술 문서 작성 완벽 가이드(Docs for Developsers)는 테크니컬 라이터로 업무 수행 중인 담당자들의 현장이야기도 포함되어 있어 다른 회사의 상황도 살펴 볼 수 있다.

20230512_185351.jpg

 

이번에 리뷰할 책은 Docs for Developers (기술 문서 작성 완벽 가이드) 책을 제공받았습니다. 현재 개발자로써의 취업이 각광 받으면서 개발 후 기술적인 문서를 작성하는 중요성도 많이 대두되고 있습니다.

 

 

SE-624ca4b9-1974-42e6-9326-dc745d8a730b.jpg

 

 

본 책에서는 기술적 문서 작성을 차근차근 어떠한 관점에서 작성을 해야하는지 예를 들어서 설명해주고 있습니다. 제일 눈에 띄었던 점은 어떠한 상황에 적절하게 활용해야 하는 템플릿도 설명하여 좋았습니다.

 

 

책을 읽으면서 개발자로써 기술적인 문서 작성을 기초부터 다질 수 있는 책이였으며, 추후 업무에 적용을 하는데 있어서도 추천드리고 싶은 책입니다.

마지막으로 좋은 책 제공과 기회를 주신 한빛미디어 담당자 분들께 감사 드립니다. 6월에도 내용이 탄탄한 도서를 읽고 빨리 리뷰를 남기고 싶습니다.

 

"한빛미디어 <나는 리뷰어다> 활동을 위해서 책을 제공받아 작성된 서평입니다."

 

1.png

 

 

문서화

개발자들에게 문서화는 정기적인 운동처럼, 중요하고 필요하지만 없어도 당장은 티가 안나는, 중요하지만 결국 문제가 터지고 나서야 중요성을 알게 되는 그런 오묘한 것이라고 생각합니다.

 

소프트웨어 개발을 배우는 과정에서 문서화를 자세히 언급하는 곳은 많지 않습니다. 그렇기 때문에, 많은 개발자에게 “기술문서 작성”을 포함한 글쓰기 와 문서화는 익숙하지 않습니다.

 

뿐만 아니라, 업무를 하는 과정에서도 당장 쌓여있는 task를 처리하는 것이 이미 만들어진, 그리고 언제 다시 바뀔지 모르는 것을 문서화하는 것보다 훨씬 효과적이라고 생각하기 때문에 문서화에 소홀해지기 마련입니다.

 

시간이 지나면서, 문서화로 인한 장점이 훨씬 더 많다는 것과 이에 대한 체계적인 접근의 필요성을 국내의 기업들도 느끼기 시작했는데요. 이를 전문적으로 하는 Technical Writter, Developer Relation 등의 직군들이 등장하기 시작했습니다.

 

그럼에도 불구하고 개발자 혹은 개발조직과 연관되어 업무를 하는 사람들은 위의 전문가 그룹 만큼은 아니지만, 기술 문서를 작성하는 방법을 알고 있으면 좋은 것이 많은데요. 오랜만의 완벽 가이드 라는 글자를 제목에 활용한, 그리고 그만한 가치가 있는 멋진 도서가 등장했습니다.

 

책의 구성과 목차

 

2.png

 

 

이 책에서는 기술 문서를 만들기 이전, Cog.ly라는 가상의 api 서비스를 제안하고 이 서비스를 개발 / 사용하는 이해관계자들의 상황을 설명하는 것으로 기술 문서의 필요성을 이야기하는 것으로 시작합니다.

  • 이후 (다른 프로덕트들처럼) 문서화를 먼저 계획하고 초안을 만들고, 피드백 하는 과정에서 챙겨야 할 체크리스트들을 자세히 설명하고
  • 실행코드나, 이미지 같은 시각화 마지막으로 문서를 어떻게 유지, 배포할 것인지 에 대한 내용을 설명합니다.
  • 원서의 저자는 구글, 리눅스 제단, 스트라이프, MS 등의 기업에서 문서화 관련 업무를 하던 분들이었던만큼 많고 자세한 내용을 담고 있으며
  • 추가로, 국내 기업의 Technical Writter 들과도 인터뷰를 통해 어떤 역량이 필요한지, 혹은 이 직업으로 어떤 과정들을 거쳤는지 등을 다루고 있습니다.

 

3.png

 

 

마지막으로 기술 문서 작성에 관심을 갖는 사람들을 위해 미처 이 도서에 담지 못한 내용들을 레퍼런스로 달아두었기에 학습이나 실습이나 큰 도움이 되리라 생각합니다.

 

4.png

 

 

책의 주요 특징

책의 내용은 특정 프로그래밍 언어나 프레임워크가 아닌 가상의 서비스를 전제로 다뤄지고 있습니다.

 

그래서 이에 대한 제한이 없는 대신, 서비스가 IT 프로덕트가 아니라면 소개하는 원칙들을 서비스에 적용하기 위해 조금 시간이 필요할 수 있습니다.

 

물론 책의 제목 자체가 “기술문서” 를 가정하고 만들었기 때문에 큰 문제는 아닙니다.

 

한편 “글쓰기 자체”를 다루기보단, 기술 문서는 어떤 것들로 구성하는 것이 왜 좋은지와 같은, 조금 더 큰 관점에서 설명들이 이루어집니다.

 (가령 아래의 예시에서 글의 문체나, UI / UX 적인 관점에서의 페이지 색상 등은 내용에 비해 상대적으로 중요하지 않습니다)

 

5.png

 

 

책은 332페이지로 내용이 꽤 많은 만큼 한번에 다 읽기는 어렵지만, 책에서 장을 넘어갈 때마다 주요 내용들을 “요약” 을 통해 정리 해주기 때문에 처음 읽을 때나, 이후에 실제로 문서를 만들며 읽을 때나 활용할 수 있는 여지가 많이 있습니다.

 

6.png

 

그래서

  • 이 책은 개발자에게 장기적으로 도움이 됩니다.
  • 개발 문서를 만들어야 하는 비개발직군에게도 꽤 도움이 됩니다.
  • 당연히, Technical Writing 관련 직군으로 커리어를 진행 / 준비하는 하는 사람에게는 즉시 도움이 됩니다.

 

샘플 코드, 명령어, API 호출을 포함하여 문서에서 제공한 예제들을 테스트하면 정확성 문제를 사전에 해결 하는데 도움이 됩니다.

 

이 문장에 등장하는 단어들을 바로 이해할 수 있다면 이 책을 이해하는 것은 어렵지 않습니다. 그러나 그렇지 않다면 책의 내용을 이해하기 위해 꽤 많은 시간을 투자해야 합니다.

 

그럼에도 불구하고, 개발 관련된 업무를 하고 있으며 다른 사람들이 그 개발의 결과물을 활용하는 것이 목적이라면 이 책은 아주 강력한 도움이 될 것이라 생각합니다.

 

 

한빛미디어의 <나는 리뷰어다> 활동을 위해 책을 제공받아 작성된 서평입니다.

 

 

결제하기
• 문화비 소득공제 가능
• 배송료 : 2,000원배송료란?

배송료 안내

  • 20,000원 이상 구매시 도서 배송 무료
  • 브론즈, 실버, 골드회원이 주문하신 경우 무료배송

무료배송 상품을 포함하여 주문하신 경우에는 구매금액에 관계없이 무료로 배송해 드립니다.

닫기

리뷰쓰기

닫기
* 도서명 :
Docs for Developers 기술 문서 작성 완벽 가이드
* 제목 :
* 별점평가
* 내용 :

* 리뷰 작성시 유의사항

글이나 이미지/사진 저작권 등 다른 사람의 권리를 침해하거나 명예를 훼손하는 게시물은 이용약관 및 관련법률에 의해 제재를 받을 수 있습니다.

1. 특히 뉴스/언론사 기사를 전문 또는 부분적으로 '허락없이' 갖고 와서는 안됩니다 (출처를 밝히는 경우에도 안됨).
2. 저작권자의 허락을 받지 않은 콘텐츠의 무단 사용은 저작권자의 권리를 침해하는 행위로, 이에 대한 법적 책임을 지게 될 수 있습니다.

오탈자 등록

닫기
* 도서명 :
Docs for Developers 기술 문서 작성 완벽 가이드
* 구분 :
* 상품 버전
종이책 PDF ePub
* 페이지 :
* 위치정보 :
* 내용 :

도서 인증

닫기
도서명*
Docs for Developers 기술 문서 작성 완벽 가이드
구입처*
구입일*
부가기호*
부가기호 안내

* 온라인 또는 오프라인 서점에서 구입한 도서를 인증하면 마일리지 500점을 드립니다.

* 도서인증은 일 3권, 월 10권, 년 50권으로 제한되며 절판도서, eBook 등 일부 도서는 인증이 제한됩니다.

* 구입하지 않고, 허위로 도서 인증을 한 것으로 판단되면 웹사이트 이용이 제한될 수 있습니다.

닫기

해당 상품을 장바구니에 담았습니다.이미 장바구니에 추가된 상품입니다.
장바구니로 이동하시겠습니까?

자료실