안녕하세요, 넷마블 기술관리팀 이중민입니다.
저는 넷마블에서 테크니컬 라이터로 근무 중입니다. 현재 넷마블에는 또 다른 테크니컬 라이터 분이 있습니다(지금까지 여러 가지 포스팅으로 찾아뵈었던 조병승 님입니다). 조병승 님은 약 2년 전 넷마블에 입사해 기술 블로그를 기획해 지금까지 운영해 왔고, 저는 작년 8월에 합류해 기술 블로그 운영과 기술 문서 작성, 편집, 관리를 하고 있습니다.
문득 뒤돌아보니 벌써 8개월이라는 시간이 흘렀습니다. 그런데 기술 블로그를 운영하면서 여러 가지 넷마블의 이야기를 소개했지만 정작 기술 블로그를 운영하는 테크니컬 라이터의 이야기를 한 적은 없더라고요. 그래서 넷마블 테크니컬 라이터로 8개월간 일했던 이야기를 해보려고 합니다.
기술 블로그! 기술 서적 편집과 다른 부분은 무엇일까?
기술 블로그가 어떻게 운영되어 왔는지는 이미 생후 400일을 넘긴 넷마블 기술 블로그 육아일기에 소개된 바 있습니다. 그래서 저는 실제 기술 블로그의 글을 다듬는 과정에서 있었던 고민을 이야기하고 싶습니다.
넷마블에서 테크니컬 라이터로 일하기 전에 했던 일은 IT 기술 서적을 기획, 편집, 번역하던 일이었습니다.
기술 블로그를 운영하는 목적이 IT 기술을 ‘글’ 중심으로 다루는 것이니까 비슷한 일을 했다고 말할 수 있습니다. IT 기술 서적을 기획, 편집, 번역하는 일은 보통 Microsoft Word 기준 200쪽 이상의 호흡이 긴 글을 다루는 일입니다. 그래서 많아야 2~30쪽 이내를 다루는 기술 블로그 포스팅은 “서적보다 분량이 작은 글을 다루는데 어렵기야 하겠어?”라고 가볍게 생각했던 적도 있습니다.
그런데 어떤 사실을 나열하는 서적의 편집과 상대적으로 짧은 글이라도 센스를 보여야 하는 기술 블로그 포스트를 다듬는 일은 전혀 달랐습니다. 서적은 목적성이 분명하기 때문에 재미나 개성과는 무관하게 사람들이 선택합니다. 하지만 기술 블로그 포스트는 기술적인 사실만 나열하면 비슷한 글이 너무 많습니다. 개성을 담아서 포스트를 다듬는 것은 생각보다 쉬운 일이 아니었습니다.
그리고 아무도 저에게 뭐라고 하지 않았지만, 기술 블로그라면 ‘문화’를 전해야 한다는 의무감을 가졌습니다. 지금도 의무감을 느끼고 있지만 그런 의무감을 자연스럽게 가져가려고 노력 중입니다.
저는 기본적으로 센스가 없다는 말을 듣는 사람입니다. 그래서 선택한 길은 ‘사소하지만 IT 트렌드를 최대한 담아보자’와 ‘최대한 친절한 포스트로 다듬자’입니다.
예를 들어 전혀 상관없을 것 같은 WAS 설정 파일 관리의 시작에 요즘 유행하는 ChatGPT와 같은 주제를 담아보자는 제안을 해보았습니다.
실무자라면 WAS 설정 파일 위치를 아는 사람이 더 많겠지만 그래도 모를 수 있는 사람에게 친절하게 다가가 보고자 컴파일 설치와 패키지 관리 도구의 설정 파일 위치에는 차이가 있다는 점을 소개하자는 제안도 해봅니다.
그래도 여러 가지 고민이 아직 진행 중입니다. 아마 끝나지 않는 고민이겠지요!
한편 개인적으로 남은 숙제라고 생각하는 점은 간단하더라도 TW가 할 수 있는 글쓰기와 관련한 OnStage의 포스팅으로 인사해 보는 것입니다. 올해 안에는 꼭 해내고픈 생각이 있습니다.
해보고 싶었던 일 – 기술 문서 편집, 검수, 관리
기술 블로그 운영과 함께 넷마블 안에서 생산되는 다양한 기술 문서(주로 기술 관련 각종 가이드)를 편집, 검수, 관리하고 있습니다. 평소에도 이 일은 꼭 한번 해보고 싶었습니다. IT 개발 도서는 불특정 다수를 상대로 기본적인 부분을 설명하지만 정말 서비스를 운영하는 개발자들은 어떤 시각에서 개발을 하고 그 결과를 글로 다룰까라는 점이 궁금했기 때문입니다. 또한 가끔 저자에게 질문했을 때 ‘이건 책에는 소개하기 어려운 회사의 정보입니다’라고 말하는 내용이 무엇인지 궁금했기 때문입니다.
현재 직접 작성하는 것보다는 주로 검수와 관리가 좀 더 많은 비중을 차지합니다. 처음 기술 문서 관련 업무를 맡은 것도 내부 SDK 개발 문서의 검수였습니다.
기술 문서를 작성하는 이유
실제 기술 문서를 검수해 보면서 정리해 본 기술 문서의 작성 이유와 필요성은 다음과 같습니다.
기술 문서의 작성 목적은 서로 다른 기술 스택을 보유한 개발자 모두가 협업의 본질을 이해하고, 해당 업무가 처음이더라도 원활하게 일할 수 있는 가이드나 매뉴얼을 남기는 것입니다. 기술 조직은 (당연한 일이지만) 게임 퍼블리싱 관련 수많은 협업이 진행되며, 개발자마다 전문 분야가 있습니다. 또한 처음 입사한 신입 사원부터 경력이 오래된 시니어 개발자까지 다양한 인원이 한 팀으로 일합니다. 다양한 구성원이 게임 퍼블리싱을 문제 없이 수행하려면 좋은 개발 문서 작성과 배포가 꼭 필요합니다.
넷마블의 기술 조직은 테크니컬 라이터에게 참 좋은 곳입니다. 개발 문서를 작성하는 것이 어떤 면에서는 귀찮고 어려운 일인데 모두 바쁜 시간을 쪼개서 열심히 개발 문서를 작성합니다.
테크니컬 라이터의 협업과 피드백
테크니컬 라이터의 협업은 기술 조직에서 작성하는 기술 문서의 검수, 관리에 초점을 맞춥니다. 협업의 첫 단계는 주로 협업 요청에 따라 기술 문서를 전달받고 검수하는 것입니다. 보통 먼저 전달받은 문서를 읽고 어떤 검수 방식이 적당할지를 분석한 후 여러 가지 채널로 피드백합니다.
피드백에서는 개발 문서 작성자가 문법적으로 적확/정확한 표현을 사용했는지 확인하고 추가되어야 할 설명이 있는지 등을 이야기합니다.
기술 문서 관리는 작성된 문서를 최적의 배포 형식으로 변환하고 관리하는 것입니다. 배포는 별도로 만든 개발 문서 웹 사이트나 워드프레스에 합니다.
제가 입사한 이후, 다른 테크니컬 라이터와 함께 개발 문서를 모은 별도의 웹 사이트를 리뉴얼하고 관리하는 일을 맡고 있습니다. 처음에는 “문서를 잘 다듬고 가독성 좋게 만들어야지” 정도로 생각했는데 그게 아니었습니다. 여러 부서가 만든 문서를 전체 게임 개발 과정에 맞게 배치하는 고민을 끊임없이 반복해야 하는 일이었습니다.
이전에는 문서에만 집중했다면 이제는 넷마블의 기술 조직이 어떤 일을 하는지에 관한 연관성을 더 심도 있게 파악하려고 노력합니다. 테크니컬 라이터로 일하기 전에는 단순히 개발자가 쓰는 문서의 조력자겠지라고 생각했지만 이제는 왜 테크니컬 라이터가 기술 조직의 일원인지 제대로 느끼는 중입니다.
여러 사람이 개발 문서를 쓸 때 발생한 에피소드
다수가 작성한 문서라면 회의를 주관해 주요 피드백 내용을 설명할 때가 있습니다. 실제 내부에서 개발하는 SDK 개발 문서의 검수 후 회의 과정에서 있었던 에피소드 중 하나를 소개합니다.
- 객체에 XXX 메서드를 호출한다.
- 객체에 접근해 XXX 메서드를 호출한다.
- 객체를 통해 XXX 메서드를 호출한다.
- 객체를 생성하고 XXX 메서드를 호출한다.
- 객체의 XXX 메서드를 호출한다.
- 객체에서 XXX 메서드를 이용한다.
- 객체를 생성한다. XXX 메서드를 호출한다.
해당 개발 문서는 개발 팀원 여러 명이 나눠서 작성합니다. 그런데 작성하는 사람마다 객체와 메서드의 관계를 표현하는 방법이 달랐던 것입니다. 7가지의 표현을 접한 개발 팀원 모두가 유쾌하게 웃었던 기억이 있습니다!
사실 앞 표현은 문맥상 다 같은 의미입니다. 그리고 각 표현 중 무엇이 틀렸다고 딱 꼬집어 말할 수는 없습니다. 하지만 처음 해당 문서를 보는 사람의 이해를 도우려면 개발 문서의 표현이 통일되는 것이 좋다고 판단해 논의를 거쳐 ‘객체의 XXX 메서드를 호출한다.’라고 통일했습니다.
테크니컬 라이터로 일하면서 겪었던 질문들
아무래도 ‘테크니컬 라이터 = 글을 잘 쓰는 사람’이라는 인식이 있습니다. 지금까지 근무하면서 문서 작성이나 글쓰기 관련으로 질문받았던 내용 중 인상 깊었고 도움이 될 만한 내용을 소개해 볼까 합니다.
용어 표현의 기준 알리기
가장 많았던 질문은 개발자분께 용어 선정의 기준을 문의받았던 것입니다. 보통 3가지 유형이 있습니다.
- 영어 용어를 번역해서 표기해야 하나요?
- 영어 용어를 음차(영어 발음 그대로 한글로 적는 것)해서 표기해야 하나요?
- 영어 그대로를 표기하는 게 좋나요?
보통 다음과 같이 답하는 편입니다.
- 개발자라면 모를 수가 없는 번역 용어(예: 데이터 타입 → 자료형, 오브젝트 → 객체)라면 해당 용어를 사용하는 것이 좋습니다.
- 샘플 코드나 명령어와 연관된 용어는 영어 그대로 작성하는 것이 가장 좋다고 생각합니다. 그러면 문서를 읽다가 샘플 코드나 명령어와 연관되어 생각하기 쉽기 때문입니다.
- 알파벳 철자가 많은 영어 단어는 한글로 음차해서 표현하면 좋습니다.
실제로 개발할 때 참고하는 각종 자료는 영어인 경우가 많습니다. 스택오버플로나 깃허브의 이슈도 영어로 질문과 답변을 하며, 대부분 유명한 기술의 개발 문서도 영어입니다. 따라서 핵심 용어라면 번역해야 한다는 부담보다는 영어 그대로 혹은 음차해서 사용하는 것을 추천하고 있습니다. 개발 문서를 보는 대상에게 가장 익숙한 용어로 통일하면 충분하다고 생각하기 때문입니다.
한편 개발 문서에서 어떤 용어를 사용할 때 신경 쓰이는 지점은 아마 외래어표기법일 것입니다. 한글의 경우 보통 표준국어대사전과 우리말샘에서 외래어표기법을 확인할 수 있기 때문에 해당 부분을 검색하면 된다고 알리기도 합니다.
특히 우리말샘에서는 외래어표기법의 규범 표기를 알려주거나 미확정이면 미확정이라는 점을 안내합니다. 외래어표기법이 헷갈린다면 참고하면 좋습니다.
그런데 외래어표기법이 꼭 맞지는 않습니다. 대표적으로 Python의 외래어표기법이 ‘파이선’이지만 현업에서는 ‘파이썬’이라고 표기하는 사례가 있습니다. 외래어표기법이 중요하며 지키면 좋지만 더 중요한 것은 용어를 통일해서 사용하는 것입니다. 이점은 꼭 강조합니다.
글쓰기 팁
용어 표현의 기준만큼이나 많이 받았던 질문입니다. 다들 글을 잘 쓰는 법을 많이 물어보셨습니다. 저로서는 솔직히 난감한 질문이기도 합니다. 글쓰기를 잘한다는 것은 객관적인 정답이 없고, 꾸준히 글을 써보는 것이 중요하다고 말하는 건 너무 막연한 말이기 때문입니다.
그래서 다음과 같이 개발 관련 글을 쓸 때 신경 쓰면 좋은 내용을 몇 가지 정리해서 알려드리고 있습니다.
무엇을 쓸지 제목 정리하기
무엇을 쓸지 키워드나 제목을 나열해 본 후 문서 모음의 목차(Table of Contents, ToC)를 만들어 볼 것을 추천합니다.
특히 개발 문서를 자주 작성하는 팀이라면 설명할 내용을 목차로 정해 팀 전체의 템플릿으로 정해두는 것이 좋다는 말을 자주 합니다.
예제나 샘플 코드 먼저 정리 및 작성하기
주제와 흐름이 정리되어 있어도 막상 글을 쓸 때는 막막하기 마련입니다. 그래서 글쓰기 전에 문서에 들어갈 예제나 샘플 코드를 먼저 발췌하거나 작성한 후 해당 샘플 코드가 어떻게 동작하는지 한 번 글로 작성해 볼 것을 많이 권합니다. 명령어 기반 가이드라면 필요한 명령어와 결과를 정리하면 좋습니다. 일단 코드나 명령어라도 들어가 있으면 글을 쓴 느낌이 들기 때문이죠. 그 후 코드나 명령어 동작 설명에서 꼭 필요한 기본 개념을 추리고 필요한 그림 등을 챙기면 어느 순간 문서의 내용이 거의 완성될 것이라고 이야기합니다.
원인과 결과 관계 맞추기
개발자의 글은 소설이나 시가 아닙니다. 많은 개발자가 작성하는 코드에 논리적인 흐름이 있듯이, 개발 문서도 어떠한 원인 때문에 결과가 나왔다는 논리적인 흐름 혹은 개발 순서가 문서에 잘 표현되면 충분히 좋은 글이라고 이야기합니다. 실제로도 그렇습니다.
퇴고
프로그래밍할 때 한 번에 원하는 기능을 실수 없이 구현하는 개발자는 아마도 없을 겁니다(저는 아직 본 적이 없습니다). 또한 팀 내부에서는 개발 완료되었다고 하더라도 다시 QA 등을 거쳐서 만든 기능에 문제가 없는지 점검할 것입니다.
글쓰기도 마찬가지입니다. 한 번에 깔끔하게 글을 잘 쓰기는 불가능합니다. 프로그래밍 후 디버깅하듯이, 개발 완료되어도 QA를 거치듯이 글을 쓴 후 스스로 잘못 작성한 부분이 있는지, 혹은 빠진 부분이 있는지 등을 확인하는 것이 글쓰기를 잘하는 지름길이라는 이야기를 자주 합니다.
물론 “프로그래밍하기도 바쁜데 글을 쓰고 퇴고할 시간까지 있을까?”라고 생각하는 분도 계십니다. 그때 저는 이렇게 말합니다.
“언제든 연락해 주시면 글을 잘 다듬을 수 있게 도와드리겠습니다”
연락주시는 분의 글은 열심히 다듬고 피드백하고 있습니다.
좋은 문서 작성 도구는 무엇일까?
저는 내가 글쓰기 편한 도구라면 좋은 문서 작성 도구라고 이야기합니다. 개발 문서를 작성한다면 다음 소개하는 조건을 만족하면 더 좋습니다.
- 웹 페이지로 변환하는 데 대응하도록 HTML 혹은 마크다운으로 내보내기(Export)가 가능
- 버전 이력과 수정 이력을 남길 수 있는 도구
현재 많은 사람이 사용하는 문서 작성 도구에는 Microsoft Word, Google 문서, 컨플루언스(Confluence) 등이 있고, 최근에는 노션(Notion)도 많이 사용합니다. 이러한 문서들은 대부분 앞 두 가지 조건을 충족합니다.
추가로 마크다운(Markdown)과 버전 관리 시스템 기반으로 개발 문서를 관리한다면 Visual Studio Code를 추천하는 편입니다. Visual Studio Code는 기본적으로 확장 프로그램을 이용해 마크다운 문법 하이라이팅 및 미리보기 등을 지원합니다.
특히 Visual Studio Code를 활용할 만한 분야라면 실제 개발하는 도구 안에서 문서를 작성할 수도 있기 때문에 편리하다는 말도 잊지 않습니다.
앞으로 더 하고 싶은 일
앞에서 말한 원칙 이상으로 기술 문서를 효율적으로 작성하는 방법을 고민해 이를 자료로 남기는 일입니다. 굳이 자료라고 표현한 건 문서가 아니라 요즘은 다양한 미디어 형태로 만드는 것이 더 좋다고 생각하기 때문입니다. 단순한 글쓰기 가이드보다는 정말 도움이 될 수 있는 시스템이나 서비스 측면으로 무엇인지 고민해 보고 싶습니다.
한편 테크니컬 라이터가 기술 조직에 기여하는 최상의 형태는 “개발 문서나 관련 콘텐츠를 큐레이팅(curating)할 수 있는 상태로 만드는 것 아닐까”라는 생각을 했습니다. 문서를 잘 만들어서 문서 안의 원하는 정보를 빨리 찾는 것은 중요합니다. 하지만 궁극적으로는 프로젝트별로 꼭 필요한 문서나 콘텐츠만 골라서 제공하는 것이 더 효율적이라는 생각이 들었기 때문입니다. 그러려면 문서의 디지털화는 기본이고 기술 조직 전체의 상황에 맞춰서 문서를 선택적으로 배포할 수 있는 시스템 구축이 중요하다고 생각합니다. 품질 좋은 개발 문서 작성과 함께 기술 조직에 최적화된 문서 배포 시스템을 구축하는 것이 앞으로 해야 할 테크니컬 라이터의 지향점일 것으로 생각합니다. 한편으로는 최근 등장한 ChatGPT와 같은 새로운 기술이나 서비스에 계속 관심을 두고 어떻게 이를 적용할 수 있을까에 관한 고민도 지속해야 한다는 생각이 듭니다.
지금까지 생각했던 이야기를 마무리하고 나니 너무 거창한 포부를 밝힌 거 아닐까 슬슬 걱정이 되고 있습니다. 그래도 목표는 큰 것이 좋다고 했던가요? 열심히 해보려고 합니다. 그리고 가끔은 거창한 포부에 대한 고민의 흔적을 기술 블로그에 나눌 수 있도록 해보려고 합니다. 점점 완숙한 테크니컬 라이터가 되는 모습을 응원해 주시면 감사하겠습니다.