내부 문서와 외부 문서 작성은 어떻게 다른가
원문: Sarah Maddox, "Writing internal vs external docs: what's the difference"
테크니컬 라이터로서 저는 커리어 대부분을 외부 사용자를 위한 문서 작성 및 관리 업무에 주력해 왔습니다. 여기서 '외부 사용자'란 저와 같은 조직에 속해 있지 않은 사용자를 말하며 이런 유형의 문서는 종종 '고객 대상 문서(customer-facing docs)'라고도 불립니다. 오픈소스 문서를 몇 년 간 다룬 경험도 있으며 현재는 내부 문서를 작성하고 있습니다. 내부 문서란 같은 조직 (여기서는 구글) 내에서 일하는 사람들을 위한 문서를 의미합니다. 제 테크니컬 라이팅 커리어 내내 주요 독자는 소프트웨어 엔지니어 같은 개발자였고 그 대상이 외부든 내부든 변함없었습니다. 그렇다면 내부 문서를 작성하는 일과 외부 문서를 작성하는 일은 어떻게 다를까요?
내부 문서 작업을 시작한 건 거의 3년 전쯤입니다. 이 역할을 맡자마자 (사실은 그보다도 앞서 면접을 준비하던 단계부터) 내부 독자를 위한 문서 작성과 외부 독자를 위한 문서 작성의 차이점과 공통점에 대해 고민하기 시작했습니다.
제 생각에는 내부 독자를 위한 문서 작성 및 관리는 외부 독자를 위한 문서 작업보다 오픈소스 문서 작업과 더 비슷합니다.
내부 문서 작업이 외부 문서 작업과 어떻게 다른지에 대해 몇 가지 생각을 정리해 보았습니다. 내부 문서의 경우 다음과 같은 특징이 있습니다.
문서화 대상 시스템의 코드에 독자가 접근할 수 있습니다. 종종 사용자는 채팅 시스템이나 이슈 트래커를 통해 개발자에게 직접 질문을 던질 수 있습니다. 흥미로운 점은 좋든 나쁘든 테크니컬 라이터인 저에게도 그런 방식으로 직접 연락이 오는 경우가 많다는 것입니다!
시스템을 개발하는 엔지니어들은 새로운 기능을 추가하거나 시스템의 중요한 업데이트를 할 때 문서의 가치를 이해하고 기꺼이 문서에 기여하는 경우가 많습니다.
시스템을 사용하는 내부 엔지니어들도 문서를 업데이트할 수 있으며, 실제로 그렇게 하고 있습니다.
오픈소스 문서 작업에서 효과적인 몇몇 기법은 내부 문서 작업에도 유용하게 적용됩니다. 이 글의 뒷부분에 제가 추천하는 방법들을 소개해 두었습니다.
변하지 않는 점들도 있습니다.
테크니컬 라이터는 늘 부족합니다. 하지만 조직에서 어느 정도 자율성을 보장해 준다면 내부 문서를 다룰 때는 이 문제를 상대적으로 더 유연하게 풀어갈 수 있다고 생각합니다.
테크니컬 라이터의 일은 매우 중요합니다. 다른 사람들이 문서에 기여하더라도 그 모든 내용을 구조화하고 이해할 수 있게 만드는 건 결국 테크니컬 라이터입니다.
팀의 기여 문화를 만드는 doc sprints, doc fixits 활동을 기획하세요
오픈소스 세계에서 doc sprints는 사용자들이 문서 작성에 기여하도록 독려하기 위해 자주 활용되는 활동입니다. doc sprint는 보통 2~3일 동안 진행되며, 특정 제품이나 툴에 대한 문서를 함께 작성하기 위해 사람들이 모여 협업하는 활동입니다. doc fixit도 유사한 활동이지만 새로운 문서를 만드는 것보다는 여러 문서 관련 이슈(버그)를 수정하는 데 목표를 둡니다.
doc sprints와 doc fixits는 매우 유용한 활동입니다.
문서 업데이트 작업에 여러분과 엔지니어들이 일정 시간을 할당할 수 있습니다. 특정 기간 동안 이 작업에만 집중하도록 하면 시간 활용이 효율적일 뿐만 아니라 목표에 대한 명확한 인식도 생깁니다.
여러 사람이 동시에 관련 문서를 함께 작업하게 되므로 질문을 하거나 조언을 구하기가 훨씬 수월해집니다. 다른 업무 중인 사람을 따로 불러내서 방해하지 않아도 되니까요.
doc sprint나 fixit 활동에 참여한 경험은 엔지니어에게 문서를 직접 업데이트할 수 있다는 자신감을 심어줍니다. 행사 기간 동안 여러분이나 다른 참여자들로부터 배울 수 있으며, 다음 문서 작업에 나설 때 유용하게 쓸 수 있는 팁과 툴들을 얻어 갈 수 있습니다.
행사에 대한 기대감을 조성하면 사람들의 참여를 독려하는 데 큰 도움이 됩니다.
운이 좋다면 스낵이나 머핀, 몹시 중요한 초콜릿(!) 같은 간식 예산도 조금 마련할 수 있을지 모릅니다.
doc sprint나 doc fixit 활동을 직접 운영해 보고 싶다면 예전에 쓴 글 '오픈소스 doc sprint를 운영하는 법'에서 유용한 팁들을 확인하실 수 있습니다. 조직의 규모와 참여할 수 있는 엔지니어의 수에 따라 달라지겠지만 이 글에 소개된 많은 기법들은 내부에서 진행하는 doc sprint나 fixit에도 적용할 수 있습니다. 그동안 저는 doc sprint와 doc fixit에 대한 글을 여러 차례 써 왔습니다.
문서화에 엔지니어와 동일한 툴을 활용하세요
가능하다면 변경사항 리뷰, 이슈 트래킹, 소스 위치 관리와 같은 부분에서 엔지니어들이 사용하는 툴과 동일한 툴로 문서 퍼블리싱 환경을 구축하세요. 이런 접근 방식을 '코드처럼 다루는 문서(Docs as Code)'라고 부르기도 합니다.
저에게 이 방식의 가장 큰 장점은 문서에 기여하고자 하는 엔지니어들이 완전히 새로운 툴셋을 배울 필요가 없다는 점입니다. 이건 특히 중요한데, 대다수의 엔지니어는 문서에 정기적으로 기여하는 것이 아니라 간헐적으로만 참여합니다. 그럴 경우 매번 새롭게 툴셋을 익혀야 하는 부담이 생기죠.
엔지니어에게 테크니컬 라이팅의 기본기를 교육하세요
제가 일하는 환경에서 테크니컬 라이터의 중요한 역할 중 하나는 엔지니어들에게 문서를 어떻게 구조화하고 작성할지 코칭하는 일입니다. 왜일까요? 제가 경험한 모든 테크니컬 라이터의 역할에는 하나의 공통점이 있었는데, 테크니컬 라이터는 늘 부족하다는 점입니다. 그래서 우리는 한정된 시간 내에서 팀과 조직의 목표에 가장 큰 영향을 줄 수 있는 최선의 방법을 고민하게 됩니다.
엔지니어에게도 명확한 글쓰기 능력은 반드시 갖춰야 할 중요한 역량 중 하나입니다. 사용자 대상 문서는 물론 설계 문서, 보고서, 다양한 커뮤니케이션 문서도 직접 작성해야 하기 때문이죠. 커뮤니케이션을 잘 할 수 있는 능력은 엔지니어의 커리어에서도 확실한 경쟁력으로 작용합니다. 실제로 우리가 제공하는 테크니컬 라이팅 교육 과정은 매번 정원의 두 배 이상 신청자가 몰릴 정도로 높은 수요를 보이고 있습니다.
엔지니어에게 테크니컬 라이팅의 기본 개념을 가르치는 단기 교육 과정을 운영해 보고 싶다면 구글에서 공개한 테크니컬 라이팅 교육 과정을 참고하세요.
단순히 지식만 전달하는 데 그치지 않도록 팁 하나를 더 드리자면 엔지니어들이 자신의 문서 모음에 직접 적용해 볼 수 있도록 정보 아키텍처 템플릿과 예시도 함께 제공해 보세요.
독자의 입장에서 문서를 바라보세요
엔지니어에게 이해시켜야 할 아주 중요한 개념 중 하나는 바로 '독자'입니다. 누구를 위해 글을 쓰는지, 독자가 무엇을 알고 싶어 하는지를 인식하는 것이 핵심이죠.
이 개념은 특히 내부 엔지니어가 다른 내부 엔지니어를 대상으로 문서를 작성할 때 더 어려워집니다. 시스템을 만든 엔지니어는 자신의 독자를 잘 알고 있다고 생각하기 쉽습니다. 독자는 어차피 자신과 같은 내부 엔지니어들이니까요.
하지만 그게 정말 그럴까요? 그렇기도 하고, 아니기도 합니다. 그들 사이의 공통점은 많지만, 알고 싶은 정보는 서로 다릅니다.
내부 시스템은 마치 벽돌을 층층이 쌓아 올린 구조와 비슷합니다. 각 계층을 만드는 엔지니어는 그 아래층을 기반으로 작업하게 되죠. 잘 설계된 구조라면 상위 계층은 하위 계층에서 제공하는 API나 프레임워크를 활용하게 됩니다.
따라서 내부 엔지니어라고 해서 자신이 기반으로 삼고 있는 시스템을 속속들이 알 필요는 없습니다. 물론 그런 지식은 유용할 수 있고, 흥미롭기도 하겠죠. 하지만 엔지니어에게 진짜로 필요한 것은 API와 프레임워크의 사용법을 이해하는 것입니다. 자주 사용되는 자동차 운전과 정비공의 비유를 빌리자면 자동차의 구조를 이해하는 것은 운전에 도움이 되고, 운전이 더 재밌어지도록 만들 수도 있습니다. 그러나 실제로 운전을 시작하기 전에 자동차의 모든 작동 원리를 자세히 배울 시간이나 의지가 있을까요? 그렇지는 않겠죠.
참고로 2014년에 제가 썼던 관련 글이 하나 있습니다 ('개발자가 업무를 수행하는 데 필요한 문서란 무엇인가').
이 주제에 관하여 ChatGPT는 뭐라고 할까요?
ChatGPT에게 이런 질문을 던져 보았습니다. "테크니컬 라이터로서 내부 엔지니어링 독자와 외부 엔지니어링 독자의 다른 점은 무엇인가요?"
ChatGPT:
테크니컬 라이터에게 있어 내부 엔지니어 독자와 외부 엔지니어 독자의 구분은 작성되는 기술 정보의 의도된 독자가 누구인지에 따라 달라집니다.
내부 엔지니어 독자는 보통 같은 조직 내의 엔지니어, 연구원, 기술 인력 등으로 구성되며, 이들은 회사 내부의 용어, 절차, 시스템에 익숙하고, 제시된 기술 정보에 대해 더 깊이 이해하고 있을 가능성이 높습니다. 내부 엔지니어를 대상으로 문서를 작성할 때는 테크니컬 라이터가 보다 전문적인 기술 용어를 사용할 수 있으며 더 높은 수준의 사전 지식을 전제로 삼을 수 있습니다.
반면 외부 엔지니어 독자는 고객, 파트너, 공급업체 등 조직 외부의 이해관계자들로 구성될 수 있습니다. 이들은 회사 내부의 용어, 절차, 시스템에 익숙하지 않을 가능성이 높습니다. 외부 엔지니어를 대상으로 문서를 작성할 때는 일반적으로 잘 알려지지 않은 전문 기술 용어나 약어는 피하고, 명확하고 간결한 언어를 사용하는 것이 중요합니다. 또한 테크니컬 라이터는 외부 독자가 제시된 기술 정보를 정확히 이해할 수 있도록 배경 정보와 맥락을 보다 충분히 제공해야 할 수도 있습니다.
요약하자면 내부 엔지니어 독자와 외부 엔지니어 독자의 차이는 기술 정보 및 회사 내부 시스템·절차에 대한 익숙함에서 비롯됩니다. 테크니컬 라이터는 서로 다른 두 독자층에게 효과적으로 기술 정보를 전달하기 위해 문체와 세부 설명의 수준을 적절히 조정해야 합니다.
거의 정확하네요!
혹시 빼먹은 게 있을까요?
그렇다면 제게 알려 주세요. 🙂
