[TW] 기술 문서 작성 5단계

시작하며

안녕하세요. 카카오엔터프라이즈에서 테크니컬 라이터 업무를 진행하고 있는 테크니컬라이팅팀의 Crystal(김유리)과 Sandy(차신영)입니다. :)

이전 포스팅(Technical Writer에서 Technical Communicator로…)에서는 Technical Communication에 대한 정의와 역사 그리고 어떤 업무를 하는지에 대해서 알아보았습니다. 지난번에도 잠깐 언급했듯이 해외에서는 테크니컬 라이팅의 학위 프로그램도 존재하며, 학계에서는 관련 프로세스가 확립 되어있는데요. 이를 바탕으로, 이번 포스트의 주제는 기술적인 정보를 특정 독자들에게 정확하고 명확하게 전달하기 위해 어떤 프로세스로 진행해야 하는지에 대해 간단히 말씀드리려고 합니다.

Kieran Morgan의 Technical Writing Process라는 책과 소프트웨어 사용자 문서 프로세스(Software user documentation process, ISO/IEC 15910) 표준을 기반으로 한, 카카오엔터프라이즈의 기술 문서 작성 과정을 지금부터 소개해드리겠습니다.

과연 여러분이 예상하는 기술 문서 생성 과정과 같을지, 한번 생각하고 읽으시면 더 흥미롭게 읽으실 수 있을 것 같습니다. :)

테크니컬 라이팅 프로세스

다음은 Technical Writing Process 책에서 발췌한 테크니컬 라이팅 프로세스입니다.

저희 테크니컬라이팅 팀에서도 위의 테크니컬 라이팅 5단계를 바탕으로 카카오엔터프라이즈 환경에 맞게 기술 문서를 생성하고 있는데요. 각 단계별 상세 내용을 살펴보도록 하겠습니다.

기획(Plan)

첫 번째 단계는 문서 기획 단계로, 프로젝트 Kick-off 미팅에서 논의되는 것이 가장 이상적입니다. 테크니컬 라이터는 보통 프로젝트 매니저와 다음의 항목들을 정의합니다.

[표 1] 기획 단계에서 정의되는 항목
구분	설명
문서 작성 범위	개발 Phase에 따라 산출되는 문서의 종류나 콘텐츠가 다른 경우 등을 고려한 문서 작성 범위 정의 - 다국어 버전 필요 시, 번역 언어 정의
문서 이해관계자	문서 산출과 관련된 모든 이해관계자 정의 - 초안 작성자, 테크니컬 라이터, 문서 검토자, 피어 리뷰(Peer Review) 진행자, 문서 최종 승인자, 문서 배포자 등 정의
프로세스	각 프로젝트 특성에 따른 프로세스 정의 - 예를 들어, 이미 문서 초안이 존재하는 경우, 초안 작성 단계 생략 후 검수 단계부터 진행
문서 작성 도구	문서 초안 작성 도구 선택 - 사내 부서별로 사용하는 문서 작성 도구(Google Docs, Wiki, Notion, Markdown Editor 등)가 다를 수 있기 때문에 문서 작성 도구 사전 협의
파일 형식	문서 파일 형식 정의 - 문서 작성 도구에 따라 Export할 수 있는 파일 형식이 다르기 때문에, 파일 산출 형식(PDF, HTML 5 등)을 정의 - Web으로 제공 시에는 보안 사항 등도 함께 정의
문서 일정	문서 생성 관련 템플릿 전달, 초안 완료, 1차 검수본 전달, 2차 검수본 전달, 피어 리뷰 완료, 최종 문서 배포 등의 일정 수립

구조화(Structure)

두 번째 단계는 목차 구조화 단계입니다. 기획 단계에서 초안 작성자와 템플릿 등이 지정된 후, 본격적으로 초안 작성자와 테크니컬 라이터는 회의를 통해 문서의 목차(Table of Contents)를 함께 구성합니다. 목차만 잘 구성해도 문서 작업의 절반이 끝났다고 자신 있게 말할 수 있을 정도로, 목차 구성은 테크니컬 라이팅의 핵심 작업이라 할 수 있습니다.

문서 구조화는 레퍼런스 문서를 분석하고, 가독성, 독자의 편의성 등을 고려해야 하는데 이 과정이 익숙하지 않은 개발자들의 경우 목차 작성에 많은 어려움을 호소하는 경우가 있습니다. 따라서 목차 작성은 본격적인 문서 작성 전, 테크니컬 라이터와 함께 진행하시면 더욱 좋을 것 같습니다.

카카오엔터프라이즈 내부적으로는 문서별 템플릿과 스타일 가이드, 목차 구성 가이드를 활용하고 있는데요. 아래와 같은 페이지를 통해 개발자들과 테크니컬 라이터들이 효과적인 목차 구성을 위해 협업하고 있습니다.

문서 작성(Write)

세 번째 단계는 초안 작성자가 초안을 작성하고, 해당 초안을 테크니컬 라이터가 리라이팅(Rewriting)하는 단계입니다. 국내의 경우 외국에 비해 문서화의 중요성에 대한 인지도가 상대적으로 떨어지기 때문에, 문서 작업은 개발과 별개인 부차적인 업무로 생각되는 경우가 많습니다. 각 개발 세부 단계마다 문서를 작성하지 않고, 개발을 모두 완료한 후에 문서 작성을 시작하면, 이슈 대응, 긴급 프로젝트 투입 등의 이유로 시간에 쫓겨 결국 반쪽 짜리 문서가 만들어지기 쉽습니다.

위와 같은 문제는 문서 작성에 얼마나 많은 시간이 소요되는지 파악하지 못해 생기게 되는데요. 문서의 내용이나 난이도에 따라 다르겠지만 ISO/IEC 표준에 따르면 문서 한 페이지의 초안을 작성하는 데 1시간이 소요된다고 합니다. 예를 들어 30장의 문서를 작성하기 위해서는 30시간이 필요한 것입니다. 다시 말해 하루 8시간씩 4일 정도를 꼬박 문서 작업에 몰두해야 한다는 계산이 나옵니다. 하지만 이렇게 하루 종일 문서 작업에만 집중하는 것은 현실적으로 불가능하며, 다른 업무를 동시에 처리하다 보면 결국 하루에 3~4시간도 문서 작업에 할당하기 힘들어집니다. 이런 현실을 고려하면 보통 예정된 문서 초안 일정이 몇 주씩 늦춰지게 되며, 이렇게 초안이 늦춰지면 다음 단계인 "리뷰(Review)" 단계에 할애할 시간이 단축되고, 이는 곧 문서 품질 저하를 의미합니다. 따라서 정확한 일자에 초안이 완료되는 것이 매우 중요하다고 할 수 있습니다.

[표 2] 문서 작성 소요 시간 (ISO/IEC 15910-2002) (출처: Sigasi)
	ISO/IEC 15910-2002	READ ME 1ST(Sun)
Writing	1 hour/page	3-5 hours/page
Reviewing	0.5 hours/page	1-3 hours/page
Editing	~2.5 hours/page	0.2 hours/page
Indexing	-	5 hours/page
Proofreading	0.25 hours/page	-
Production	8-10 days	5% of a project
Project management	~100 hours/project	10-15% of a project

개발자의 초안 작성이 완료되면, 테크니컬 라이터의 리라이팅 작업이 시작됩니다. 개발자들은 보통 "이 내용은 개발자라면 모두 알고 있을 거야"라고 가정하고 반드시 필요한 정보를 생략하고 본론으로 바로 넘어가는 경향이 있는데요. 기술 문서는 회사 외부의 초급 개발자들도 쉽게 따라 할 수 있도록 최대한 상세하게 작성해야 합니다. 테크니컬 라이터는 초안 문서에 누락된 설명을 보완 및 수정하고, 테크니컬 라이팅 4대 원칙인 명확성, 간결성, 정확성, 일관성에 입각하여 초안을 리라이팅 한 후, 가독성과 사용성 측면에서 문서를 편집합니다. 리라이팅의 경우, 기술적인 내용을 정확히 알아야 초안을 수정할 수 있기 때문에 본격적인 수정 및 편집 작업 전 초안 작성자에게 관련 교육을 요청하고, Q&A를 주고받는 작업이 진행됩니다. ISO 표준에 따르면, 한 페이지당 수정 및 편집 단계에 각각 0.5시간, 2.5시간까지 소요되므로 총 3시간의 작업시간이 필요합니다.

리뷰(Review)

세 번째 단계는 리뷰(Review) 단계로 작성된 문서를 기술적인 측면과 스타일적인 측면에서 확인하는 단계입니다. 기술적인 리뷰에서는 문서의 기술적인 내용에 오류가 없는지에 초점을 맞춰 진행되며, 보통 초안 작성자와 초안 작성자가 속한 팀 내의 다른 개발자가 진행합니다.

기술적으로 수정 또는 보완되어야 하는 내용이 있을 경우, 다시 "작성(Write)" 단계로 되돌아가 문서 작업을 진행합니다. 반면 스타일적인 리뷰는 동료 테크니컬 라이터와 문서 내 용어/표현의 통일성, 스타일 가이드/용어집의 준수 여부, 맞춤법 등을 리뷰하는 과정으로 피어 리뷰(Peer Review)라고도 합니다. ISO 표준에 따르면, 페이지당 내용 리뷰에는 30분, 단순 교정 작업에는 약 15분이 소요됩니다.

배포(Publish)

마지막 단계는 최종 문서를 고객에게 전달하기 위한 배포 단계입니다. 문서가 종이 책이나 PDF 포맷으로 배포되었던 과거와는 달리, 최근에는 웹 상에 문서를 배포하는 것이 추세입니다. 웹 배포의 장점은 누구나 쉽게 URL을 통해 문서에 접근할 수 있다는 점이지만, 특정 고객사에게만 배포되어야 하는 문서나 기밀문서의 경우에는 PDF 포맷을 사용하거나 Google Docs 등의 권한 관리 기능을 사용하여 특정 사용자에게만 권한을 부여하는 작업을 하기도 합니다. 테크니컬라이팅 팀에서는 문서 배포 이후의 문서 데이터베이스, 버전 관리도 진행합니다. 시간이 흘러 누군가가 "3년 전에 A 고객사한테 전달했던 그 문서가 필요해요"라는 요구에 당황하지 않고 대응하기 위해서입니다.

다음은 위 5단계를 거쳐 배포가 완료된 기술 문서의 예시인데요. 최근 트렌드에 맞게 웹에 배포한 모습입니다. 아래 이미지의 문서 정보에서 볼 수 있듯이 각 문서별로 버전을 명시해 이후 문서 관리 목록에서 누락되지 않도록 관리하고 있습니다.

마무리하며

지금까지 테크니컬 라이팅이 진행되는 단계별 프로세스를 살펴보았는데요. 위의 프로세스에 따라 작업이 진행되면 이상적이지만, 현실적으로 이 프로세스가 제대로 지켜지지 않는 경우가 많습니다. 예를 들어, 테크니컬 라이터들에게 협업 요청 없이 초안을 바로 작성하거나, 초안 문서 리라이팅이 70% 정도 끝난 시점에서 개발에 엄청난 변경점이 생겨 초안부터 다시 작성해야 한다거나, 국문 버전만 요청했던 고객이 갑자기 영문이 필요하다고 요청하기도 하며, 프로젝트 일정 변경 사항이 제대로 전달되지 않는 등 여러 크고 작은 문제에 직면합니다.

창작 글쓰기뿐만 아니라 기술적 글쓰기에도 상당한 노력과 인내가 필요합니다. 앞서, 초안글 한 페이지 작성하는데 보통 한 시간이 걸린다고 말씀드렸는데요. 그렇다면 총 작업 시간은 얼마나 걸릴까요? STC(The Society for Technical Communication)의 통계에 따르면 한 페이지당 총 작업시간은 약 8시간이 소요된다고 합니다. 따라서 문서 한 페이지를 제대로 작성하려면 이렇게 엄청난 시간과 노력이 필요하다는 점을 프로젝트 참여자 전원이 인지하고, 테크니컬 라이팅 프로세스의 존재를 인지하며, 최대한 프로세스를 준수하려고 노력할 때 문서화 작업은 더욱 효율적으로 진행되며, 문서의 품질은 향상될 것입니다.

저희 테크니컬라이팅 팀에서는 앞으로도 테크니컬 라이팅 프로세스에 대해 홍보하고, 테크니컬 라이팅에 관련한 유용한 주제들을 기술 블로그에 기고할 예정입니다. 앞으로도 많은 관심을 부탁드리며, 글을 마치겠습니다. 감사합니다. :)