전체 제목은 "Crafting Docs for Success: An End-to-End Approach to Developer Documentation"입니다.
직역하면 "성공을 위한 문서 작성: 개발자 문서의 종합적인 접근 방식"으로 번역할 수 있습니다. "Crafting"이라는 표현은 뭔가 공장에서 찍어낸 제품보다는 수작업으로 뭔가 장인이 만들어내는 느낌이 있습니다. 아마 저자도 바닥부터 시작해서 기술 문서와 개발자 포털 사이트를 만들어낸 경험을 나름대로 담아내고 싶었던 것이 아닌가 싶습니다. 물론, 아쉽게도 그런 마음은 담겨 있지만, 모든 지식을 담아내지는 못했습니다.
https://www.amazon.com/Crafting-Docs-Success-End-End-ebook/dp/B0CD9RHQ4F/
저자(Diana Lakatos)가 2018년 platformOS 팀에 합류하면서 문서화 프로세스와 개발자 포털을 만들게 됩니다. 물론 그전에 문서가 전혀 없었던 것은 아니지만 체계적이지 못했고, 말 그대로 바닥부터 프로세스를 만든 경험을 이 책을 통해 공유합니다.
2024년에는 UK Technical Communication Awards에서 이 책으로 상을 받기도 했다고 합니다.
10개의 챕터로 구성되어 있고, 많은 책들이 그러하듯이 전반부 챕터는 자세하게 다루고 후반부로 갈수록 개념적인 부분만 다루는 느낌이 있습니다. 각 챕터별로 요약과 개인적인 감상을 남겨봅니다.
1. Approaches
문서화 프로젝트를 어떤 관점으로 접근할지에 대한 고민을 담았습니다. 가장 강조하는 것은 "documentation as a product"입니다. 문서를 제품의 부산물로 바라볼 건지 아니면 제품 그 자체로 바라보는지에 따라 전반적인 프로세스와 조직 내에서 중요도가 달라질 수 있습니다. 전문적인 테크니컬 라이터를 채용하지 않는 이유도 제품 그 자체로 문서를 바라보지 않기 때문이죠.
Your developer documentation is naturally linked to the product it documents, but considering the crucial role it plays in the adoption, use, and marketing of your product, it should be considered a product in its own right.
디자인 씽킹에 대한 언급도 꽤 많은 분량을 두고 설명합니다. 출판사(Apress)의 편집자의 의견이 담긴 것일 수도 있고, 실제 저자가 일하는 환경에서 UX 팀과 긴밀하게 일했기 때문이기도 합니다. 이상적인 방법이기는 하지만, 꽤 많은 리서치와 노력이 필요한 부분입니다.
2. Foundations
문서화 프로젝트에서 퍼소나, 사용자 조사에 대한 이야기는 많이 하지만, 실행하는 것은 쉽지 않습니다. 저자의 경우 개발자 포털을 만들고 제품 전체에 대한 콘텐츠 우선순위 등을 정해야 하는 방대한 작업이기 때문에 이런 작업을 같이 했지만, 일반적인 작은 규모의 프로젝트에서는 일단 시작하는 것부터 하는 경우가 많겠죠. 그럼에도 기회가 된다면 작은 부분이라도 적용해 보는 것은 나쁘지 않습니다. 제대로 하려면 이 책에서 언급된 내용보다는 UX 리서치 관련 책을 참고하세요.
If you would like to get some more insights about user research methodologies, I recommend you to read Universal Methods of Design – 125 Ways to Research Complex Problems, Develop Innovative Ideas, and Design Effective Solutions by Bella Martin and Bruce Hanington and Just Enough Research by Erica Hall.
3. Editorial Workflow
테크니컬 에디터로서의 역할까지는 아니더라도, 기술 문서를 담당한다면 개발팀에서 작성한 콘텐츠를 검토하고 이를 배포하는 역할을 담당할 수 있습니다. 모든 일이 그렇지만 균형이 중요합니다. 프로세스를 만들었다고 해서 그 프로세스를 엄격하게 거쳐야만 통과할 수 있게 하는 것이 아니라, 유연한 대응이 필요합니다.
개발팀에서 코드 리뷰를 하는 프로세스를 가지고 있다면 그 프로세스를 가져와서 사용하는 것도 나쁘지 않습니다.
As authors and reviewers communicate, always seek to understand. Ask open questions to clarify intentions, and be receptive to new perspectives. Know that everyone regardless of their skill level can contribute meaningfully. Strive to communicate with compassion, kindness, and awareness of yourself and others.
4. Content Production
요즘은 거의 마크다운이 대세인 것 같습니다. 개발자에게도 익숙한 방식이라 테크니컬 라이터만 익숙해지면 됩니다. 다만, 스타일 가이드나 형식을 잘 정하고 점진적으로 개선할 수 있는 방안은 필요합니다.
Following the Content First approach means that you start developing content (or at least defining the structure of your content) relatively early on in your process before you start working on wireframes, layouts, or the technical implementation.
요즘에는 템플릿과 스타일 가이드만 가지고 AI를 통해 초안을 생성한 후 이를 보완하는 글쓰기 방식도 늘어나는 것 같습니다.
5. Implementation
사이트(문서)를 구현하는 방식은 엔지니어링 지원이 있는(또는 본인이 능력이 있는) 경우에는 커뮤니케이션을 통해 할 수 있지만, 그렇지 않은 경우에는 어떤 것을 선택해야 하는지 애매할 수 있습니다. 책에서는 이런 이런 방법이 있다라고 하면서, 그런데 우리는 직접 개발했어라고 마무리 지어서 어떻게 하라는 건지 당황스럽긴 합니다.
Our documentation site is built on platformOS, and we store the code base and content files in a public GitHub repository. We are now also working on combining platformOS with GitHub and a static site generator to build a solution for quickly implementing documentation sites that follow the Docs-as-Code methodology and the editorial workflow we use. Besides standard web technologies like HTML, CSS, and JavaScript (including JSON and AJAX), we use a couple of languages like YAML, Liquid, and GraphQL in our code.
오픈소스 문서화 플랫폼에서 제공하는 기본 기능만 사용한다면 어떤 것이든 선택해서 사용하면 되고, 뭔가 커스터마이징이 필요하다고 한다면 엔지니어링 도움을 받던지 아니면 상용 제품을 사용하는 것이 좋습니다. AI가 도와준다고 하더라도 뭔가 설정 등에서 꼬여버리면 운영 중인 사이트에 문제가 생길 수도 있거든요.
6. Community
피드백 채널을 만들어놓았다고 해서 끝나는 것이 아니라 이를 관리하고 유지해야 합니다. 때문에 피드백 또는 커뮤니케이션 채널을 만드는 것은 주의해야 합니다. 괜히 시작했다가 이도 저도 아니게 유지된다면 오히려 고객 입장에서 불만 요인이 될 수 있거든요. 처음에는 다른 관련 기술 커뮤니티에 참여하는 정도부터 시작하는 것도 나쁘지 않습니다.
When I talk about contribution, I always start with emphasizing that every input from your team, users, clients, business partners, and sometimes even from individuals with vastly different areas of expertise that changes, improves, or moves your documentation forward can be considered contribution. In this sense, writing content is only a small portion of all contributions to the documentation.
7. Accessibility and Inclusion
접근성과 포용성은 일반적인 웹사이트 지침과 크게 다르지 않습니다. 사용하는 문서화 도구가 이를 지원하는지 확인하고 필요하다면 요청해야 합니다. 직접 구현하기에는 너무 할일이 많아질 수 있습니다.
I hope this chapter has provided valuable insights that inspire you to take a proactive approach toward accessibility and inclusiveness, thus contributing to a more accessible Internet, one documentation at a time.
8. Sustainability
좋은 성능을 내는 문서화 사이트를 만드는 것이 환경에 긍정적인 영향을 준다는 내용입니다. 지속가능성을 제쳐놓더라도 문서화 사이트의 성능은 사용자 만족도에 큰 영향을 미칠 수 있는 부분입니다. 가능한 문제가 되는 부분은 모두 제외하고 사용자가 빠르게 문서에 접근할 수 있게 하세요.
9. Team
이 책에서 가장 아쉬운 부분입니다. 어떻게 보면 저자의 경험을 좀 더 풀어낼 수 있는 부분인데, 너무 교과서처럼 정의만 하고 끝내버렸습니다.
10. Measures of Success
문서화의 성과를 드러내는 척도를 만들어내는 것도 좋지만, 우선 중요한 것은 지원팀과 긴밀한 협력 관계를 가지는 것입니다. 내부 팀원들의 만족도를 먼저 이끌어낼 수 있다면 그 이후 비즈니스에 미치는 긍정적인 효과도 자연스럽게 끌어낼 수 있습니다. 한번 성과를 인정받고 끝낼 것이 아니라면 지속할 수 있는 성과를 만들 수 있는 환경을 만들어야 합니다.
https://documentation.platformos.com/
