안녕하세요. CLOVA 기술 문서 작성 및 관리 업무를 맡고 있는 Technical Writing 팀 강정일입니다.
제가 테크니컬 라이팅(Technical writing) 분야에서 일한 지 어느덧 10년 정도 되었습니다. 하지만 이 글을 보고 계신 분들 중 많은 분들이 테크니컬 라이팅이란 단어를 처음 듣거나, 들었어도 정확히 어떤 일을 하는 지는 잘 모르실 수도 있다고 생각합니다. 한국만 해도 대학에 테크니컬 라이팅과 관련된 전공이 없어서인지 이런 직무를 가진 분들을 만나는 게 쉽지 않습니다. 특히 한국 소프트웨어 산업의 특성 상, 설계 문서나 API 레퍼런스와 같은 기술 문서를 다루는 테크니컬 라이터를 만난다는 것이 더욱 어려운 일인 듯 합니다. 이런 척박한 환경에서 테크니컬 라이팅 분야에 대한 최신 뉴스나 업무에 대한 지식, 전략 등을 얻기 위해 대부분의 테크니컬 라이터들이 인터넷 검색이나 팀원 간의 정보나 경험 공유에 의존하고 있는데요. 이번에 Write the Docs 컨퍼런스에 참석하여 이런 부분에 대한 갈증을 많이 해소할 수 있었습니다. 그래서 제가 보고 들은 점들을 공유드리고 싶어서 이렇게 블로그에 글을 올리게 되었습니다. 제가 공유드리는 내용 중 'Learning to love release notes' 세션에 관한 내용은 릴리즈 노트 작성 방법에 관한 내용이어서 테크니컬 라이터뿐 아니라 개발자분들에게도 꽤 유용할 것이라고 생각합니다.
Write the Docs 소개
Write the Docs(이하 WTD)는 커뮤니케이션, 문서, 그리고 사용자를 연구한 경험을 서로 공유하는 커뮤니티입니다. WTD는 특히 소프트웨어 산업과 관련된 분야에 좀 더 집중하고 있습니다. 이 커뮤니티는 매년 정기적으로 봄에는 미국 포틀랜드에서, 가을에는 체코 프라하에서 WTD 컨퍼런스를 열고 있는데요. WTD 컨퍼런스에서 참석자들은 각자가 문서 및 프로젝트를 관리하면서 얻은 경험을 공유하고, 좀 더 관심있는 주제가 있으면 토론도 하면서 새로운 사람과 뉴스를 접할 수 있는 기회를 가집니다. 참고로 Serizawa Susa님이 지난 2018년 4월, 파리에서 열렸던 API the Docs 컨퍼런스에 다녀오신 후 API the Docs 컨퍼런스 참관기를 남기셨었는데요. 여기서 소개되었던 API the Docs는 WTD 컨퍼런스에 영향을 받은 컨퍼런스 시리즈입니다. 관심 있으신 분들은 Serizawa Susa님이 쓰신 글도 같이 읽어보시면 좋을 것 같습니다.
이번에 제가 참석한 컨퍼런스의 정식 명칭은 'Write the Docs Prague 2018'입니다. 이름에서 알 수 있듯이 체코 프라하 시내의 Autoklub에서 열렸으며, 9월 9일부터 3일간 진행되었습니다. 이번 WTD 컨퍼런스에서는 아래와 같은 행사들이 진행되었습니다.
- Writing day, Reception(9/9)
- Conference talk(9/10~9/11)
- Unconference and light talks
컨퍼런스 현장의 분위기를 좀 더 생생하게 전달해드리고 싶어 행사장 모습을 사진으로 몇 장 남겨왔습니다.
아래 사진은 컨퍼런스가 진행되었던 메인 홀과 발표가 진행되는 모습입니다.
홀의 반대편에서는 특정 주제를 선정하여 대화를 나눠보는, 이른바 'Unconference'라는 이름의 행사가 진행되고 있었습니다. 아래 사진에서 Unconference에 올라온 주제들을 보실 수 있습니다.
이번 글에서는 제가 들었던 세션 중 가장 기억에 남는 두 세션과 각 세션에 대한 제 소감을 공유해드리려고 합니다.
Tackling technical debt in the docs
이 세션에서는 영국 Sage사에서 테크니컬 라이터로 일하고 있는 Louise Fahey가 문서 프로젝트에서 기술 부채(technical debt)의 개념이 무엇이고, 그것을 어떻게 발견하고 제거해야 하는지에 대한 자신의 경험을 공유하였습니다.
기술 부채의 정의
기술 부채라는 용어는 흔히 소프트웨어 개발에만 관련된 용어로 인식되고 있는데요. 이 세션에서 Louise는 소프트웨어 개발 프로젝트와 문서화 프로젝트를 크게 구분하지 않고, 기술 부채에 대해 다음과 같이 정의했습니다.
기술 부채란, 프로젝트 내에서 어떤 문제를 해결할 때 장기적인 관점에서 기획 및 검토하지 않고 임시적인 방편으로 그 문제를 해결하여, 그로 인해 나중에 큰 비용이 발생할 수 있는 요소를 말합니다. Louise는 애자일 개발 프로세스의 성명서를 작성했던 멤버 중 하나인 Ward Cunningham의 말을 인용하여 "중요한 일이 연기된 것"이라고 다시 짧게 줄여 말했습니다.
Louise는 문서 프로젝트의 기술 부채는 lack of skill과 lack of standard에 의해 발생한다고 이야기했습니다. 문서 프로젝트에서 문서 작성 및 관리에 사용된 도구나 기술은 세대를 거듭해 변화하게 되는데요. 그때마다 콘텐츠, 이미지, 스타일 관련 파일 등이 불필요하게 남게 될 수 있습니다. Lack of skill은 이런 자산과 이 자산들로 인해 문서 관련 업무가 느려지고 관리가 어려워지는 것을 뜻합니다. 그리고 lack of standard는 문서 작성 또는 리뷰에 필요한 스타일 가이드나 템플릿이 없거나, 이런 것들이 오래된 채로 방치되어 문서의 일관성이 깨지고 문서의 품질이 낮아지는 것을 의미하고 있습니다.
기술 부채 인지 방법
기술 부채를 인지하는 방법은 다양하겠지만, 특히 문서 프로젝트에서는 다음과 같은 신호를 주시해야 한다고 말했습니다.
- 문서를 빌드할 때 점점 느려지고 있지 않은지?
- 사용되지 않는 콘텐츠 파일, 이미지나 스타일은 없는지?
- 깨진 링크나 북마크가 있지는 않은지?
- 로컬라이제이션 작업에 콘텐츠 번역과 상관 없는 이슈가 발생하고 있지 않은지?
기술 부채 해결 방법
소프트웨어와 마찬가지로 이런 부채를 계속 방치하면, 해결하는 데 드는 비용이 겉잡을 수 없이 늘어나고, 결국 문서의 품질이 떨어질 수 밖에 없다고 했습니다. 이를 방지하기 위해 다음과 같은 절차로 기술 부채를 줄일 것을 조언해주었습니다.
- 우선 기술 부채가 무엇이 있는지 파악하고 나열할 것
- 파악한 기술 부채를 분류할 것
- 각 기술 부채를 해결하는 데 얼마의 비용이 들지 판단할 것
- 기술 부채에 대한 우선 순위를 결정할 것(긴급한 것인지? 중요한 부분인지? 독자가 계속 원하고 있는 것인지?)
- 기술 부채를 해결할 경우 얻게 되는 이익이 무엇인지 파악할 것(기술 부채 해결의 당위성 확보)
- 기술 부채를 해결할 시간을 확보할 것
- 기술 부채를 해결한 후 개선된 결과를 측정하고 공유할 것
위와 같은 활동을 반복하여 기술 부채가 없거나 문제가 되지 않는 상태까지 도달했다 하더라도, 이런 상태를 계속 유지하기 위해서는 다음과 같은 것들을 계속 수행해야 합니다.
- 수시로, 또는 주기적으로 프로젝트를 검토(audit)하는 시간을 가질 것
- 스타일 가이드나 템플릿을 만들고 그것을 계속 업데이트하려고 노력할 것(Lack of standard를 해결하는 것은 기술 부채가 없는 상태를 유지하는 데 도움이 됨)
- 사용자의 피드백을 받고 수시로 반영할 것
- Definition of Done을 정의할 것(DOD는 문서 작업의 퀄리티를 보장하는 도구로 사용될 수 있음)
소감
문서에 대한 기술 부채는 이희승님께서 Armeria 오픈소스화 이야기에서 '문서화 부채(documentation debt)'라는 표현으로 먼저 다뤄 주셨는데요. 저는 그 글을 읽을 때까지도 '부채'라는 말이 '소프트웨어 개발' 프로젝트에만 관련이 있다고 생각했지 '문서' 프로젝트까지 연관있다고 생각하진 못했습니다. 그래서 이번 WTD 컨퍼런스 발표 주제가 공개된 후 이 세션의 제목을 보았을 때, 대체 어떤 이야기가 나올지 몹시 궁금했었습니다. 그렇게 참석하게 된 세션에서 저는 문서 프로젝트를 볼 수 있는 새로운 시각을 얻게 되었습니다. 제가 이해한 것은, 소프트웨어든 문서든 콘텐츠를 만들기 위해 '프로세스와 비용'이 필요하다면, 그에 상응하는 '부채'라는 개념이 어떻게든 있을 수 있다는 것입니다. 또한 세부적인 내용이 다를 순 있겠지만, 프로젝트를 다룬다는 개념에서 문서 프로젝트도 소프트웨어 개발 방법론 등을 접목할 수 있다는 것을 알게 되었습니다.
현재 저는 현업으로 돌아와 그 동안 밀려있던 부채를 갚으려고(?) 노력 중입니다. CLOVA 기술 문서 저장소의 리소스 파일을 다시 확인하고 있으며, 최근 빈번한 로컬라이제이션 작업 시 불필요하게 발생하는 비용을 줄이기 위해 스크립트를 만들고 정보 구조도 재편하고 있습니다. 문서 프로젝트에서 기술 부채가 더이상 늘어나지 않도록 스타일 가이드나 템플릿을 구비하는 등 장기적인 관점에서도 노력하고 있습니다.
Learning to love release notes
이번 꼭지에서 공유해드릴 내용은 아마 개발자 분들에게도 많은 도움이 되지 않을까 생각합니다. 이 세션에서는 영국의 스타트업 기업인 Improbable사에서 테크니컬 라이터로 일하고 있는 Anne Edwards가 릴리즈 노트를 작성하는 방법에 대한 몇 가지 팁을 공유했습니다.
릴리즈 노트의 정의
Anne Edwards는 서두에서, 자신이 생각하는 릴리즈 노트의 정의에 대해 먼저 이야기했습니다. Anne이 말한 릴리즈 노트의 정의는 다음과 같습니다.
- 소프트웨어 배포와 함께 게시되는 점 목록(bullet list)의 글
- Bug fixes, New features, Known issues로 구성되는 문서
- 짧고 간결하게 표현된 정보
- 마지막 순간에 미친 듯이(?) 뽑아낸 정보(발표자의 개인적인 견해였지만, 저는 무척 공감했던 의견)
릴리즈 노트의 구성 요소
이어서 릴리즈 노트의 구성 요소인 Bug fixes, New features, Known issues 항목이 무엇인지도 다음과 같이 정의했습니다.
- Bug fixes: 지속적으로 사용자에게 불편을 주던 오류나 버그 따위를 고친 것
- Features: 지속적 또는 오랫동안 사용자가 원하거나 요청한 것을 추가한 것
- Known issues: 가끔 또는 자주 발생하는 오류나 불편사항(아직 고치지 못했거나 고치는 방법을 모름)이 있음을 알리는 것, 또 그것을 언젠가는 고칠 것임을 예고한 것
릴리즈 노트 작성이 어려운 이유
Anne은 자신이 입사 면접 시 '현재 일에서 즐기지 않는 일이 무엇인가?'라는 질문에 릴리즈 노트를 작성하는 일이라고 응답한 이야기를 공유하며, 다음과 같은 이유로 릴리즈 노트를 작성하는 것이 어려운 일임을 설명했습니다.
- 릴리즈 노트의 내용은 연관성이 거의 없는 항목이 나열됨
- 따라서, 다른 문서 대비 맥락 정보의 환기(Context switching)가 자주 일어남
- 각 항목에 대한 조사도 많이 해야 함
- 간결하면서도 많은 정보를 정확하게 전달해야 함(간결한 글을 쓰는 것과 많은 정보를 담은 글을 쓰는 것은 상충되는 부분이 있어서 공존하기가 어려움)
- 맥락이 이어지지 않기 때문에 다른 문서보다 쓰는 것이 재미있지 않음
릴리즈 노트 작성 노하우
Anne은 자신의 경험을 살려 릴리즈 노트를 잘 쓸 수 있는 몇 가지 노하우를 알려주었습니다.
첫 번째는 릴리즈 노트를 쓸 때 'Expand out and Simplify' 전략을 쓰라는 것입니다. 릴리즈 노트를 쓸 때 처음부터 간결하게 쓰려고 노력하다 보면, 꼭 들어갔어야 할 많은 정보들이 빠져 있거나, 의미가 모호해진 노트를 쓰게 된다고 말했습니다. 이에 Anne은 처음에는 글이 길더라도 정보를 빠트리지 않고 정확하게 쓰는데 집중하고(Expand out), 그 뒤에 중요하지 않거나 보조적인 부분을 빼면서 간결화(Simplify)하는 전략을 사용하라고 알려줬습니다.
두 번째로 사용자 관점에서 쓰도록 권고했는데요. 예를 들어 System에 A라는 모듈이 추가되었을 때 'System에 A 모듈 추가'와 같이 시스템 입장에서 릴리즈 노트를 쓰는 경우가 많이 있습니다. Anne은 'XX 기능(A 모듈)을 사용할 수 있게 됨'과 같이 A라는 모듈이 추가되면서 사용자, 혹은 사용자의 워크플로우에 영향이 미친 부분에 초점을 맞춰서 글을 쓰라고 권고했습니다.
마지막으로는 유머나 개성이 드러나는 방식으로 글을 쓰는 것을 지양하라고 말했습니다. 친근하게 글을 쓰게 되면 글의 간결함이 떨어집니다. 이렇게 되면 독자는 필요한 정보를 얻기 위해 추가적인 인지 활동을 수행해야 합니다. 더구나 유머러스하거나 친근한 표현들은 각 독자의 성향마다 다르게 수용될 수 있으므로 조심해야 합니다. 그리고 그런 표현이 들어간 글은 대게 글쓴이의 개성이 드러나게 되는데 이는 회사나 서비스, 제품을 대변하는 글에는 맞지 않다고 말했습니다.
다음으로 Anne은 작성자가 릴리즈 노트를 쉽게 작성하면서 독자가 빠르게 정보를 습득할 수 있도록 템플릿을 사용하도록 권장했고, 다음과 같은 3가지 템플릿을 제공했습니다.
You can now ... | ...을 할 수 있음...이 가능해짐 | Bug fixes나 Feature 항목에 사용할 수 있는 패턴 |
X now/no longer does Y when Z. | Z일 때 Y하지 않고 X하게 됨 | 과거(Y)와 현재(X)의 차이를 설명하고 맥락(Z)를 나타낼 때 좋은 패턴 |
X now/no longer does Y. This means you no longer /now need to do Z. | Z를 하기 위해 Y 대신 X를 해야 함 | 과거(Y) 대신 현재(X)를 수행하여 목표(Z)를 이룰 수 있도록 가이드할 때 좋은 패턴. 사용자의 워크플로우를 업데이트하도록 가이드해야 할 때 좋음. |
릴리즈 노트 세션 요약
이 세션에서 나온 많은 설명을 간단하게 요약해 표로 만들어봤습니다.
|
|
|
|
|
소감
이 세션을 듣고 나서 테크니컬 라이터인 저 조차도 아직 릴리즈 노트를 제대로 작성하지 못하고 있다는 것을 깨닫고 큰 반성을 하게 되었습니다. 릴리즈 노트에 대한 발표자의 깊은 내공을 느끼면서 릴리즈 노트의 정의를 다시 한번 생각하게 되었습니다. 현재 맡고 있는 문서 프로젝트뿐만 아니라 앞으로 작성하게 될 릴리즈 노트에도 이런 내용들을 잘 한번 적용해 볼 생각입니다(다만, Anne이 알려준 템플릿은 각 언어의 특성에 맞게 조금 다듬을 필요가 있습니다). 릴리즈 노트와 관련된 스타일 가이드나 템플릿도 잘 정립하여, 앞으로 기술 부채가 쌓이지 않도록(최소한 덜 쌓이도록)할 예정입니다.
마치며
WTD 컨퍼런스는 위에서 공유해드린 세션 뿐 아니라, 다른 여러 세션들도 테크니컬 라이팅 직무를 수행하는 데 도움이 될 만한 많은 정보를 제공했습니다. 또한 이에 대해 다른 참석자들과 의견 공유를 할 수 있는 좋은 기회까지 만들어주었습니다. 제가 이런 기회를 가질 수 있도록 도와준 회사와 동료들에게 감사를 드립니다. WTD 컨퍼런스에서 얻은 정보와 노하우를 적극적으로 공유하고, 현업에서도 잘 활용해 보겠습니다.
글을 마무리하면서 제가 이번에 느낀 팁이라고 생각되는 것을 하나 알려드리자면, 메인 행사만큼이나 리셉션 이벤트도 중요하다는 것입니다. 보통 컨퍼런스 행사장이 유럽이나 북미 지역인 경우가 많아서, 한국에서 참석하려면 긴 시간 동안 이동을 해야 합니다. 그렇게 되면 비행 시간이나 시차 때문에 매우 피곤한 상태로 도착하게 되는데요. 컨디션을 잘 조절해야 컨퍼런스 메인 세션 때 집중할 수 있기 때문에 저는 보통 전야제와 같이 메인 행사 전날 밤에 진행되는 리셉션 이벤트는 거르고 일찍 수면을 청했었습니다(주위, 혹은 제 옛 동료들도 주로 컨퍼런스 메인 세션에만 집중하거나, 추가적으로 스폰서 부스를 돌아다녀보는 정도로 행사 참석을 마무리한다고 하더군요).
그런데 이번에는 이상하게 리셉션에 꼭 참석해보고 싶어서 마음먹고 한번 참석해보았는데요. 이 결정이 제가 가지고 있던 컨퍼런스에 대한 인식을 많이 바꿔주었습니다. 메인 컨퍼런스 시작 전날 3시간 정도 진행된 리셉션에서 많은 사람들과 인사할 수 있었고, 그 중 일부와는 정말 편하게 대화할 수 있게 되었습니다. 물론 WTD 컨퍼런스 기본 방침이 참석자들 간의 교류를 강조하고 있다는 것도 한 몫했습니다. 여하튼 이렇게 리셉션에 참석하고 나니 메인 컨퍼런스 일정 내내 리셉션에서 친해진 참석자와 세션에서 들은 내용을 공유하거나 논의하게 되었고, 각자의 경험이나 전략 등에 대해서도 얘기를 나누게 되었습니다. 보통 이런 컨퍼런스는 혼자 가게 되는 경우가 많아 행사 내내 스스로 주변을 겉돌고 있다는 느낌을 받았는데요. 이번엔 행사를 상당히 즐길 수 있었습니다. 식사를 하거나, 준비된 음료와 스낵을 먹을 때도 친해진 사람들과 끊임없이 이야기하면서 보내게 되어 외롭지(?) 않았습니다.
사실 그동안 컨퍼런스에 참석하면 뭔가 어색하기도 하고 주위 참석자들과 대화 나누는 게 어려웠는데요. 저는 그 이유가 저의 부족한 언어 스킬이나 조금 다른 외향에 있다고 생각했었습니다. 하지만 그렇지 않았습니다. 만약, 저와 비슷한 패턴으로 컨퍼런스에 참석하셨던 분들이 계시다면, 다음엔 꼭 메인 컨퍼런스 일정 전에 진행되는 리셉션 이벤트에 참석하셔서 적어도 2~3명 정도의 참석자와 연락할 수 있는 관계를 만들어보시는 것은 어떨까요? 분명히 기분 좋은 경험을 하시게 될 겁니다.