책 제목은 DOCS LIKE CODE(코드처럼 문서 다루기)입니다. 요즘에는 많은 곳에서 이런 방식을 채택하고 있지만, 얼마 전까지만 해도 이런 문화가 널리 퍼지지는 않았습니다. 2022년에 출간된 책이라 좀 오래된 내용일 수도 있습니다.
https://www.amazon.com/Docs-Like-Code-Collaborate-Documentation/dp/1387531492
저자인 Anne Gentle는 Rackspace와 Cisco에서 오픈스택(OpenStack)과 오픈스택 기반 클라우드 제품 문서화를 담당했습니다. Rackspace의 동료였던 Diane Fleming과 Kelly Holcomb이 책을 쓰는데 도움을 준 것 같습니다.
종이책 기준으로 96페이지 분량이고 5개 챕터와 1개 부록으로 구성되어 있습니다. 코드처럼 문서 다루기(docs like code)의 개념과 Git을 사용한 실제적인(?) 활용 방법을 설명하는데 초점을 맞추고 있습니다. Eric Holscher이 서문에 남긴 것처럼 "This book is a practical introduction to the docs-like-code mindset"이라고 설명할 수 있습니다. 이런 개념을 전혀 모르는 분들에게 사고 전환의 계기를 만들어주는거죠(물론 그러기에는 너무 책 자체의 난이도 조절에 실패한 경향이 있습니다).
* 책과 별개로 웹사이트를 통해 각 도구를 어떻게 사용해야 하는지 차근 차근 설명하고 있습니다.
https://www.docslikecode.com/learn/
* Docs like code 보다는 docs as code가 좀 더 많이 쓰이는 표현입니다.
https://www.writethedocs.org/guide/docs-as-code/
https://idratherbewriting.com/learnapidoc/pubapis_docs_as_code.html
1. Introduction docs like code
docs like code가 무엇이고 왜 사용해야 하는지 설명합니다. 코드를 개발하는 개발자의 작업 프로세스가 변화하는 것에 맞추어 문서화 프로세스도 바뀌어야 한다는 겁니다. 물론 코드를 다루는 방식도 다양하기 때문에 이것만 정답이라고 할 수는 없지만, 아래와 같은 목표를 달성할 수 있는 도구 중 가장 효율적인 것이 docs like code라고 설명합니다.
- Promote collaboration
- Get long-tail contributions
- Track doc bugs like code bugs
- Get better reviews
- Make beautiful docs
- Use developer tools and workflows
- Get value from cost-effective tools
2. Plan for docs like code
제목은 Plan인데, 개념적인 설명만 하고 갑자기 사례로 넘어갑니다. Django 문서의 상호 참조 방식이라든지, 오픈스택 문서의 저장소 관리 문제라든지 너무 구체적인 이야기로 넘어가 버립니다. 그래서 여러분은 어떻게 해야 되나요? 가 없습니다. REST API 문서화에 대한 설명도 마찬가지입니다. 너무 짧은 개념 설명과 문서 라이프 사이클까지 넓은 범위를 다루려다 보니 살짝 언급만 하고 넘어가는 수준이 되어버렸습니다.
3. Optimize docs-like-code workflows
실제적인 내용이 담겨 있습니다. 전체 책의 절반 이상을 할애한 부분입니다. 목적과 상황에 따라 문서 저장소를 어떻게 구성하고 배포할지 가이드합니다. 아쉬운 점은 각 절차에 너무 많은 내용을 소개하고 있다는 겁니다. 예를 들어 문서 빌드 시에는 "이런 이런 도구를 사용할 수 있고 이런 결과가 나옵니다"까지만 언급되어 있어서 실제 프로세스를 만들어야 할 때 어떻게 해야 하는지 살짝 모호합니다. 다음 챕터가 Tutorial이니깐 이번 챕터도 개념적인 설명으로 본다면 이해할 수 있습니다.
4. Tutorial
기존 저장소를 포크하는 내용만 다룹니다. 음. 문서 기여자에게는 적합한 설명이지만, 문서화 프로세스를 만들어야 하는 입장에서는 완벽한 튜토리얼이라고 할 수 없겠네요.
5. Lessons learned with docs like code
여기도 챕터 제목과 다르게 docs like code 문화를 정착시키기 위해서 이런저런 일을 해야 한다고 간단하게 언급하고 넘어갑니다.
