Splunk 문서팀의 경험을 공유한 책입니다. 뭔가 당장 실무에 도움이 될 만한 책인가 싶었지만, 살짝 개념적인 이야기가 너무 많긴 합니다. 2017년에 나온 책이라 일부 이야기는 요즘 프로세스에는 맞지 않을 수도 있습니다.
혹시, 이 책이 궁금하신 분들을 위해 각 챕터 내용을 살짝 요약해보았습니다(책을 다 읽긴 했지만 너무 오래 전 일이고, 직접 요약하기는 귀찮아서 요약은 AI가 ㅠㅠ).
1. Introduction
Splunk 문서팀의 경험을 바탕으로, 기술 문서 작성의 실무적·현실적 관점을 제공한다.
기존의 이론 중심 자료나 UX/마케팅 중심의 페르소나 모델이 아닌, 실제 기술 문서팀이 겪는 문제와 해법에 초점을 맞춘다.
이 책은 실무 경험과 팀의 집단 지성을 바탕으로 한 의견과 지침을 에세이 형식으로 정리했다.
2. Agile
애자일은 현실과 이론이 다르며, 대부분의 개발팀은 스크럼 등 일부만 채택하거나 변형해서 사용한다.
기술 문서팀은 정보 수집, 팀 내 소통, 변화 대응에 적극적이어야 하며, 문서도 제품의 ‘완료’ 정의에 반드시 포함되어야 한다.
직접 스크럼팀에 참여(Direct Participation)하는 방식과 별도의 문서 스크럼팀(Scrum of Writers) 방식이 있다. 직접 참여가 더 효과적이지만, 팀 규모가 커지면 부담이 커질 수 있다.
애자일은 모든 문서 작업에 적합하지 않으므로, 작업 유형에 따라 방법론을 유연하게 적용해야 한다.
3. Audience
기술 문서의 성공은 제품 지식뿐 아니라 ‘청중(독자)’에 대한 깊은 이해에 달려 있다.
청중 분석을 통해 팀 구조, 채용, 테스트, 정보 구조, 콘텐츠 형식 등 다양한 의사결정에 도움을 준다.
페르소나와 청중 정의는 다르며, 실제 문서팀에 맞는 구체적 청중 정의(예: Admin 1, Dev 2 등)를 팀 차원에서 만들어야 한다.
청중 정의는 신입·기존 라이터 모두에게 유익하며, 회사 내 다른 부서와 공유해 공통 인식을 만드는 데도 중요하다.
4. Collaborative Authoring
기술 문서는 본질적으로 협업 작업이다. 여러 라이터, SME(주제 전문가), 에디터 등과의 협력이 중요하다.
회사 스타일 가이드 활용, 정기적 동료 리뷰, 공식적 피어 리뷰 프로그램이 일관성과 품질 향상에 도움이 된다.
위키 등 개방형 저작 도구를 활용하면 내부 직원 누구나 기여할 수 있지만, 품질 관리 체계도 필요하다.
협업의 폭과 방식은 조직과 도구에 따라 다르며, 효율적 프로세스를 위해 유연하게 조정해야 한다.
5. Customer Feedback and Community
활발한 고객 커뮤니티와 직접적 피드백은 문서 품질과 제품 성공에 필수적이다.
피드백 수집은 웹 양식, 소셜 미디어, 사용자 그룹, 컨퍼런스 등 다양한 경로를 활용한다.
부정적 피드백도 개인적 감정이 아닌 개선 기회로 받아들이고, 신속하고 성실하게 응답해야 한다.
커뮤니티와의 지속적 소통은 신뢰를 쌓고, 실제 사용 사례와 요구를 파악해 더 나은 문서와 제품 개발로 이어진다.
6. Documentation Decisions
의사결정 참여자: 문서화와 관련된 의사결정에는 다양한 이해관계자가 참여한다. 팀원, 제품 관리자, 엔지니어, 고객 지원 등 여러 부서와 협업이 필요하다.
의사결정 요소: 독자, 제품 특성, 가용 리소스, 기존 문서, 사용 데이터, 피드백 등이 주요 고려 대상이다.
의사결정 프로세스: 명확한 결정 정의, 참여자 식별, 관련 요소 분석, 결정 기록 및 커뮤니케이션, 의사결정 단순화, 피드백 루프 강화가 핵심 절차다.
7. Documenting Third-party Products
상황 평가: 외부 제품 문서의 품질, 설정의 특수성, 공급사와의 관계, 독자의 필요 수준을 평가해야 한다.
문서화 범위 결정: 직접 문서화하지 않거나, 제한적 정보만 제공하거나, 외부 문서로 안내하는 등 다양한 전략이 있다. 필요에 따라 공급사와 협업하거나, 블로그/커뮤니티 등 외부 채널을 활용할 수도 있다.
8. Hiring, Training, and Managing Documentation Teams
채용: 다양한 배경과 경험을 가진 테크니컬 라이터를 채용해 팀의 전문성과 다양성을 높인다.
팀 다양성: 다양성과 포용성은 팀의 혁신과 문제 해결 능력을 증진시킨다.
교육 및 관리: 신입/기존 라이터 모두를 위한 체계적 교육과 피드백, 성과 관리, 집단 지성 활용이 중요하다.
팀 성장과 축소: 팀 규모 변화에 따라 역할과 프로세스를 유연하게 조정해야 하며, 성장기에는 복잡성 관리, 축소기에는 핵심 역량 유지가 필요하다.
9. Learning Objectives
학습 목표 정의: 사용자의 목표와 학습 목표를 구분하고, 문서 작성 시 명확한 학습 목표를 설정해야 한다.
효과: 학습 목표는 문서 작성, 조직, 유지보수, 사용성 개선에 모두 도움이 된다.
실행 방법: 출발점과 도착지(목표)를 명확히 하고, 필요시 목표를 재정의한다. 다양한 내부 자료와 피드백을 활용해 목표를 구체화한다.
10. Maintaining Existing Content
유지보수 시점: 기능 변화, 사용자 피드백, 스타일 가이드 변경, 용어 변경, UI 업데이트 등 다양한 요인에 따라 문서 업데이트가 필요하다.
업데이트 방법: 범위 평가, 영향 분석, 적절한 도구와 시점 선정, 주요 릴리스와의 동기화가 필요하다.
계획 수립: 대규모 업데이트는 사전에 계획하고, 리소스 확보와 일정 조정이 중요하다.
11. Measuring Success
성과 측정: 문서의 성공은 단순한 조회수나 다운로드 수만이 아니라, 사용성, 피드백, 고객 만족도 등 다양한 지표로 평가한다.
지속적 개선: 측정 결과를 바탕으로 문서 품질과 프로세스를 지속적으로 개선한다.
12. Organizing Documentation Tiger Teams
타이거팀 구성: 촉박한 마감이나 대규모 프로젝트 시, 임시로 여러 팀의 라이터를 모아 집중적으로 문서 작업을 수행한다.
실행 전략: 팀 리드 지정, 명확한 전략 및 계획 수립, 도구 교육, 빈번한 회의, 기여자 동기부여가 중요하다.
13. Research for Technical Writers
사전 조사: 배경 조사와 정확한 정보 확인이 필수다.
질문 기술: 적절한 질문과 전달 방식, SME(주제 전문가)와의 소통 방법을 익혀야 한다.
감사의 태도: 협업 과정에서 항상 감사의 표현을 잊지 않는다.
14. Scenario-driven Information Development
시나리오 활용: 실제 사용 시나리오를 중심으로 문서를 개발하면, 사용자의 맥락에 맞는 실용적 정보를 제공할 수 있다.
단계: 청중 정의 → 시나리오 수집 → 시나리오 작성 → 사후 검토의 순서로 진행한다.
15. Technical Editing
기술 편집의 역할: 시각, 품질, 스타일 일관성, 정보 설계 자문 등 다양한 역할을 한다.
자체 편집: 에디터가 없는 경우, 자체 스타일 가이드, 체크리스트, 동료 리뷰 등으로 품질을 관리한다.
지속적 개선 문화: 피드백과 실험, 자기 점검을 통해 문서 품질을 꾸준히 높인다.
16. Technical Verification
기술 검증 필요성: 모든 문서는 기술적 정확성 검증이 필수다.
검증 주체: SME, QA, 동료 라이터 등 다양한 주체가 참여한다.
검증 방법: 사전 준비, 리뷰, 후속 조치, 반복 개선이 중요하다.
17. Tools and Content Delivery
도구 선정: 콘텐츠 관리, 저작, 배포, SEO, 통합 등 다양한 요소를 고려해 도구를 선택한다.
위키 기반 협업: 개방형 위키 시스템은 협업과 피드백에 유리하지만, 품질 관리 체계도 필요하다.
버전 관리, PDF 생성, 콘텐츠 재사용 등: 다양한 기능 지원이 요구된다.
18~25. 협업 및 특수 환경 (Working with ~~)
고객 지원, 엔지니어, 현장, 마케팅, 제품 관리, 원격 팀, UX/디자인 등과의 협업: 각 부서와의 효과적 협업 방법, 역할 분담, 커뮤니케이션 전략을 다룬다.
SaaS 문서화: SaaS 환경의 특성(빠른 배포, 다양한 사용자 역할, 자주 바뀌는 기능)에 맞는 문서 전략과 내부 문서(런북 등)의 중요성을 강조한다.
