<Docs for Developers 기술 문서 작성 완벽 가이드> 리뷰

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

 

 

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

 

 

📚 선정 이유

개발자를 위한 독서 모임의 존재를 알게 되었다. 한 달에 한 권 개발 관련 서적을 읽고 모여 의견을 나누는 모임이었다. 5월의 책은 <Docs for Developers 기술 문서 작성 완벽 가이드>였다. 해당 모임에 참석하기 위해 이 책을 읽었다. 원래 글쓰기에 관심이 많고, 개발 문서를 잘 작성하고 싶은 니즈가 있었기 때문에 오프라인 모임까지 신청하게 되었다. 

 

 

📝 종합 감상

나는 취준생이기 때문에 아직 개발자로서 회사에서 일해 본 경험은 없다. 회사에서 작성하는 개발 문서를 만들어 본 경험은 없지만, 개인 프로젝트나 다른 분들과 팀 프로젝트를 할 때 리드미를 작성해 본 적은 있다. 리드미를 완성도 높게 작성하면 보는 사람에게 좋은 인상을 주고, 특히 면접관분들에게도 어필할 수 있다고 취업 관련 강의에서 들었다. 프로젝트에 대한 설명이나 설치 및 작동 방법, 프로젝트의 기능, 스크린 샷이나 영상 등이 잘 담긴 리드미는 좋은 첫 인상을 주기 때문에 코드에 대한 기대감도 높아진다. 내가 독자의 입장일 때도 마찬가지이다. 따라서 나는 책을 읽을 때 잘 와닿지 않는 회사의 개발 문서보다는, 프로젝트 리드미를 작성한 경험을 떠올리며 읽었다.

 

어떻게 하면 읽는 사람이 쉽고 명확하게 이해할 수 있는 글을 작성할 수 있을지에 도움이 되었다. 강아지 언어 번역기 예시 사례와 함께 순차적으로 문서 작성 하는 법을 배워서 이해가 수월했다. 특히 글을 쓰면서 겪을 수 있는 문제에 대해 어떻게 대처하면 좋을지도 같이 쓰여있어서 도움이 됐다. 예를 들어 글이 잘 써지지 않을 때나, 동료와 피드백을 주고 받을 때의 주의점 등이 그랬다. 기술 문서를 효과적으로 작성하는 방법에 관한 책이다 보니 이 책 역시 번역서임에도 불구하고 쉽게 읽혔다. 책의 모든 챕터에서 독자 입장에서 생각하라는 핵심이 강조되는데, 이 책 자체도 저자들이 읽는 사람을 고려하면서 작성했다는 것이 느껴졌다. 

 

한편으로는 "개발" 문서가 아닌, 개발 "문서"에 치중된 느낌을 받았다. 깊은 테크니컬 지식을 원해서 이 책을 읽으면 실망할 수 있다. 개발자향 첨가 수준이다. 전반적으로 문서를 제대로 작성하는 법에 대해 나오기 때문에 문서 작성 자체에 관심이 있다면 읽을만 하다. 그렇지만 2만 5천원의 가격을 주고 읽고 싶지는 않을 수 있다. 독서 모임 때도 몇 번 지적된 아쉬운 점이다.

 

한국판 부록에 수록된 국내 테크니컬 라이터 11인 인터뷰는 국내외 회사에서 일하고 계신 테크니컬 라이터 분들의 이야기를 들어볼 수 있다. 이런 직업이 있다는 것도 모르고 있었기 때문에 시야가 넓어졌다. 내가 개발자로 전향한 이유 중 하나가 이전까지는 '개발자'라는 직업과 접점이 없는 환경에서 살았고, 그 때문에 회사에서 처음 접한 개발자분들의 모습이 너무 멋져 보였기 때문인 것도 있다. 어떤 직업/일이 있다는 것을 알게된 자체가 미래에 내가 어떤 모습일지 상상해볼 여지를 더욱 제공해준다는 점에서 부록 인터뷰가 마음에 들었다.

 

 

🔖 챕터 별 감상 

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

 

1. 독자 이해하기

이전 회사에서 마침 사용자 리서치 작업을 해본 적이 있어서 그 경험을 떠올리며 읽었다. 오프라인 환경에서 FGI(포커스 그룹 인터뷰)를 진행하고, 앱 내 사용자 설문 조사를 기획했던 경험 덕분에 글이 생생하게 읽혔다. 당시 어떤 질문을 해야 하는지, 어떻게 흐름을 구성해야 하는지 고민했었다. UX 사용성 조사에도 도움이 될 내용이라 흥미로웠다. 사용자 여정 지도나 마찰 로그 등의 방법을 사용하면 더욱 완성도 높은 사용자 조사를 할 수 있을 것 같다.

 

2. 문서화 계획하기

취업 준비를 하면서 리드미가 매우 중요하다는 얘기를 들었다. 개발을 하다 보면 스스로를 위해서도 트러블 슈팅을 남기는 등의 글도 그렇고, 남들에게 보여주기 위한 개발 문서도 그렇고 문서 작성을 할 일이 참 많다고 느낀다. 어떻게 해야 문서를 효과적으로 작성할 수 있을지의 토대 세우기를 단계별로 구체적으로 알려주어서 도움이 되었다.

 

3. 문서 초안 만들기

대부분의 사람들이 콘텐츠를 읽을 때 F 패턴으로 훑어보기 때문에, 중요한 정보를 먼저 제시하고 간결하게 글을 써야 한다는 점을 배웠다. 개인적으로 글의 제목 정하는 것을 어려워 하는데 예시와 함께 구체적으로 제목을 정하는 방법을 알려줘서 유용했다. 특히 제목에서 컨텐츠 유형이 어떻게 구성될 것인지, 문서의 목표가 무엇인지까지 유추 할 수 있다는 점에서 문서의 제목이 매우 중요함을 알았다. (80, 85p)

 

4. 문서 편집하기

"개발자의 글쓰기"이기 때문에 문서 작성과 공유, 피드백을 위한 새로운 툴을 익히지 않아도 된다는 큰 장점이 있다. 코드리뷰 시스템을 문서 검토에도 활용할 수 있다는 점이 새로운 접근이었다. 깃허브와 같은 버전관리시스템을 이용하면 문장마다 코멘트를 달 수도 있고, 피드백을 받아 문서를 수정하고나면 이전의 문서와 어떤 부분이 달라졌는지도 한눈에 볼 수 있다. 피드백을 할 때는 건설적인 제안을 덧붙이는 플러싱 방법이 효과적이라는 것을 알게 됐다. (115-116p)

 

5. 샘플 코드 통합하기

샘플 코드가 가져야 하는 특징과 원칙을 알게 되었다. 샘플 코드를 위한 도구는 내용이 잘 와닿지 않았다. 직접 샘플 코드를 작성 해본 경험이 없어서 머리에 쉽게 그려지지 않았다. 공식 문서에서 봤던 샘플 코드들을 떠올리며 읽었다.

 

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

사람의 뇌가 이미지와 텍스트를 처리하는 방식을 이해하면 시각적 콘텐츠가 얼마나 이해에 도움이 되는지 알 수 있었다. 대문자로만 이루어진 문장이 읽기 힘든 이유도 글자의 높이와 크기가 같아 뇌가 이를 처리하기 어려워하기 때문이다. 프로젝트 리드미를 작성할 때 스크린샷을 첨부하는 경우가 많은데 이 때 주의해야 하는 요소를 잘 기억해두면 좋을 것 같다. (146-147p)

 

7. 문서 배포하기

한 번에 완벽한 문서를 만들고 싶어 두려움과 강박을 가지기 보다는, 일단 배포를 하고 나서 수정하거나 업데이트 해도 괜찮다. 어떤 일이든 부담이 생기게 되면 하기 싫어지고 스트레스를 받게 되므로, 일단 행동하는 것이 중요하다. (163p) 콘텐츠 배포 프로세스에 코드리뷰 프로세스를 사용하면 절차의 일관성을 보장할 수 있다. 새로운 라이브러리를 사용할 때 공식 홈페이지에 접속 하면 도구의 개념과 함께 '시작하기 페이지'로 이동 하는 버튼이 항상 같이 있었던 것이 떠올랐다.

 

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

평소에는 그냥 지나쳤었던 문서 감정 조사에 답변을 적극적으로 해야겠다는 생각이 들었다. 명확한 이해가 되지 않은 채 어림 짐작으로 받아들였던 단어에 대해 알 수 있었다. 사용자의 피드백이 유효한지 확인 할 때, 유효하다는 뜻이 정확히 무슨 의미인지 몰랐는데, 문서 피드백의 경우 문제가 문서와 관련이 있는지를 의미한다는 것을 알게 되었다. (185p)

 

9. 문서 품질 측정하기

문서의 품질을 측정하는 방법을 배웠다. 당장 쓸 일이 없어서 잘 공감이 되지는 않았다. 메트릭(측정 항목)이라는 용어가 익숙하지 않아서 조금 어려웠다. 여기부터 후반부 내용은 흥미가 급격히 떨어지게된 챕터이다. 

 

10. 문서 구조화하기 

UX에 관한 내용이었다. 역시 크게 공감되진 않는 내용이었지만 추후 홈페이지를 만들 때 도움이 될 내용이었다.

 

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

개발 공식 문서에 더이상 사용되지 않는 메소드 등이 표기되어 있는 것이 생각났다. 문서의 내용이 오래되어 이제는 쓰이지 않을 때 그 문서가 끝이 났음을 관리해주는 것 역시 사용자와의 신뢰를 높일 수 있다. 간과하기 쉽지만 중요한 핵심이며, 정성들여 작성한 문서에 대한 예의이기도 하다.