발표 제목처럼 발표 내용도 약간 혼란스러웠습니다. 중간에 경품을 뿌리면서 답변을 받고, 발표 내용도 딱 정리가 되지 않아 어떻하지 싶어 그냥 이번 발표는 AI에게 정리를 요청해보았습니다. 그런데 정리된 내용을 보니 꽤 체계적인 발표였네요. 결국 제가 문제였나 봅니다.
Stephanie Fuller(25년 경력의 시니어 테크니컬 라이터)가 발표한 "Writing the Shipwreck" 세션입니다. 발표자는 기술 문서화 환경이 매우 혼란스럽고 낡은 상태(‘난파선’)에서 어떻게 체계적으로 문제를 진단하고, 개선 계획을 수립하며, 실제로 문서 시스템을 성공적으로 전환했는지 자신의 경험을 바탕으로 설명합니다.
1. 문제 상황 진단(Shipwreck)
발표자가 처음 맡은 문서 환경은 낡은 도구(Gitbook CLI, 더 이상 지원되지 않음), 일관성 없는 스타일 가이드, 내부 프로세스 부재, 문서 품질 관리 미흡 등 여러 문제가 복합적으로 존재하는 ‘난파선’ 상태였습니다. Madcap Flare로 전환하려 했으나, 예산과 운영 환경(맥 지원 불가), 주요 고객의 요구(MK Docs로 전환) 등 현실적인 제약에 부딪혀 실패.
* 음. 좀 설명이 부족한데 일단 GitBook CLI는 최근 업데이트가 되었는지 낡은 도구라는 표현은 적절하지 않습니다. 다만 제가 기억하기로도 GitBook 자체가 꽤 오랫동안 업데이트를 하지 않고 있었고 최근 개발자 문서에 포커스를 맞추어 AI 도구 등을 추가하면서 기능 보완이 된 것 같습니다. 하여간 발표자 경험은 2023년 즈음인것 같고 그 시점의 경험으로는 적절한 설명이구요.
https://gitbook.com/docs/developers/integrations/reference
* Madcap Flare로 전환하려는 이유는 기존 팀원이 CLI 형태의 작업에 익숙하지 않아서 일반 편집 도구 형태로 전환하려고 했었는데, 결국에는 그 팀원이 퇴사하면서 그럴 필요가 없어졌다는 이야기가 섞여 있었습니다.
2. 자기 점검 및 팀 역량 평가
이런 환경에서는 단순히 주어진 업무만 하는 것이 아니라, 창의적이고 적극적으로 문제를 해결할 자세와 역량이 필요한지 스스로 점검해야 함을 강조합니다.
팀원 간 기술과 도구 사용 경험의 불일치, 내부 커뮤니케이션의 중요성도 언급.
3. 현황 분석 및 자산 파악
기존 프로세스와 도구, 팀 내외부의 활용 가능한 리소스(타 부서의 라이선스 등)를 꼼꼼히 조사.
무엇이 작동하고, 무엇이 고장 났는지, 어떤 부분이 반복적으로 문제를 유발하는지 정량적으로 기록해 경영진 설득 자료로 활용.
4. 개선 방향 및 실행 전략
정보구조(Information Architecture) 설계, 오픈소스/상용 문서화 도구 비교(MK Docs, Hugo 등), 스타일 가이드 선정 및 맞춤화(Microsoft Style Guide 활용), 커뮤니티와의 협업 등 구체적인 개선 방안 제시.
기존 문서 중 쓸 만한 부분은 최대한 살리고, AI 도구를 활용해 대량 변환 및 요약 작업의 효율성을 높임.
5. 점진적 개선과 관리
모든 문제를 한 번에 해결하려 하지 말고, 매일 조금씩 개선(Incremental Improvement).
업무량이 많거나 팀이 적을 경우, 문서의 일부만이라도 개선하는 실용적 접근법을 추천.
AI를 활용해 문서 분할, 요약, 형식 개선 등 반복 작업의 효율화 사례 공유.
6. 조직 내 설득과 협업
도구 및 프로세스 변경 시 필요한 예산, 타 부서 협조, 일정 조율 등 실무적 팁.
스타일 가이드의 중요성, 일관성 유지의 필요성, 내부 설득 논리 제시 방법 등도 다룸.
7. Q&A 주요 내용
외부에서 도구가 정해지는 경우 기대치 관리법
1인 문서팀에서 사이트 개편 우선순위와 일정 관리법
영상 등 부가 자료 업데이트 시기와 우선순위
스타일 가이드 유지 필요성 설득법 등 실질적 질문에 대한 답변
발표 자료는 github에 공개가 되어 있습니다.
https://github.com/stephffuller/word-nerd
참고 자료는 QR 코드로 공개했는데, QR 코드에 연결된 URL이 임시 URL이라 만료가 되어 버렸습니다.
일부 찾을 수 있는 링크는 따로 정리했습니다.
IA is for everybody
https://www.thesensemakersclub.com/ia-for-everybody
How to make sense of any mess
https://www.howtomakesenseofanymess.com/
Everyday Information Architecture
https://www.amazon.com/Everyday-Information-Architecture-Maria-Marquis/dp/B0DP5JDBPN
How Chunking Helps Content Processing
https://www.nngroup.com/articles/chunking/
(번역) https://brunch.co.kr/@byeon/13
(번역) https://brunch.co.kr/@shc9500/13
4 Writing the Shipwreck - Stephanie Fuller
www.flickr.com
https://youtu.be/rQI0w57iK-4?si=tdC5TS-v0Ly7Cyuq
