구름은 한 달에 한 번 수요일에 기술, 개발, 성장, 조직 문화 등에 관한 이야기를 나누는 COMMIT 세미나를 진행하고 있습니다. COMMIT은 COMMUNICATION과 IT의 합성어로 개발자가 소스 코드를 커밋하듯 IT 업계를 이루는 분들의 역량을 COMMIT하고 있어요.
2024년 11월 COMMIT 주제는 ‘기술 문서’입니다. 기술 문서는 API/SDK 가이드, 사용자 가이드/매뉴얼, 릴리즈 노트 등의 문서를 말해요. 이러한 기술 문서 관리는 단순히 내용을 정리하고 공유하는 것을 넘어, 제품의 신뢰성을 높이는 중요한 작업입니다. 효율적인 기술 문서 엔지니어링은 혼선을 줄이고, 다양한 이해관계자가 명확하게 소통하도록 돕죠.
하지만 많은 사람은 이러한 문서화 과정을 부담스럽거나 번거롭다고 느낍니다. 그렇다면, 기술 문서를 어떻게 관리해야 여러 불편을 해소하고 더 효과적으로 관리할 수 있을까요?
그 답을 LINE Plus(이하 라인)에서 도큐먼트 엔지니어링이란 개념을 도입하고 실제로 문서에 적용해 가고 있는 전정은 라인 도큐먼트 엔지니어(Documentation Engineer)로부터 들어봤습니다.
written by Seori
edited by snow
 전정은 LINE Plus, Document Engineer 글 쓰기를 좋아해 소설가를 꿈꿨었습니다. 그러다가 컴퓨터 게임에 빠져 컴퓨터 공학과에 진학하고, 개발자가 되었습니다. 개발을 하며 개발 문서를 제대로 관리하지 못하는 현실을 해결하기 위해 테크니컬 라이터(Technical Writer)로 전향했습니다. 그렇게 일한 지 어느덧 10년, 현재는 라인의 기술 문서 전반을 관리하는 도큐먼트 엔지니어로서 ‘독자를 위한 도큐먼트 엔지니어링 문화’를 만들어가고 있습니다. 기회가 닿는 대로 그 경험을 나누고자 노력하고 있습니다. |
Q. 테크니컬 라이터와 도큐먼트 엔지니어의 역할에는 어떤 차이가 있나요?
테크니컬 라이터는 이름에서부터 느껴지지만, 주 관심 분야가 글 자체이다 보니, 글을 사람이 읽기 쉽게 다듬고, 잘 쓰도록 하는 데 집중해요. 반면, 도큐멘트 엔지니어는 글뿐 아니라 전체 프로세스를 만들고, 개발자가 글을 잘 쓰게 하려면 어떻게 해야 하는지를 프로세스나 엔지니어링 기법으로 해결하는 역할을 해요.
Q. 도큐먼트 엔지니어, 어떻게 시작하게 됐나요?
도큐먼트 엔지니어라는 직책이 원래 있었는지 잘 모르겠어요. 개발자에서 테크니컬 라이터로 전향할 때만 해도 이런 직책은 없었어요. 그러다 테크니컬 라이팅을 하면서 문서와 관련된 여러 문제를 해결해 가다 보니, ‘테크니컬 라이터’라는 이름만으로는 제가 해온 일을 정의하기에 부족하다는 생각이 들었어요. 고민 끝에 ‘도큐먼트 엔지니어’라는 이름을 내세웠죠.
스스로를 도큐먼트 엔지니어라고 규정하게 된 데에는 전 직장인 LG에서 경험이 컸어요. 당시 테크니컬 라이팅을 처음 접했는데, 지금 생각해 보면 조금 예스럽긴 하지만 워드(MS Word)로 문서 작업을 많이 했어요. 워드 파일 변환이나 협업 과정에서 서식이 엉망이 되는 경우가 많았어요. 복사, 붙여넣기도 너무 많았죠. ‘이렇게 하면 안 되겠다’는 생각에 해결 방법을 고민했었어요.
결국 문서의 생명주기 전 과정을 우리가 처음부터 끝까지 만들고 테크니컬 라이터가 각 과정을 주도할 수 있어야 해결할 수 있다는 생각에 이르게 됐어요. 라인에 와서야 그 생각을 실현할 기회가 주어졌고요. 아직은 하나씩 체계를 만들어가는 중이지만요.
Q. 라인에서는 기술 문서를 어떤 프로세스로 관리하고 있나요?
프로젝트마다 조금씩 다르긴 한데, API 문서의 경우 개발자가 API 변경 사항을 위키에 작성하면, 테크니컬 라이터나 도큐먼트 엔지니어가 이를 마크다운이나 YAML 파일로 작성해요. 그런 다음 PR(Pull Request)을 올려요.
이후 개발자가 PR을 리뷰하고 승낙하면 이걸 병합(Merge)해요. 특정 브랜치에 병합한 내용은, CI/CD 파이프라인으로 자동으로 배포하죠. 기존 문서를 일부 변경할 땐, 개발자가 직접 PR을 올리기도 해요. 마크다운이나 YAML 파일을 수정하고 PR을 올리면, 제가 리뷰를 하고 병합해요. 이 역시 CI/CD 파이프라인을 통해 자동으로 배포되죠.
보통 이렇게 작성한 문서는 디벨롭 사이트에 먼저 배포해서 확인한 후 프로덕션 사이트로 배포하는 식으로 기술 문서를 관리, 배포하고 있어요.
Q. 라인의 모든 기술 문서가 이러한 절차로 관리되고 있나요?
단계는 조금 다르지만, 테크니컬 라이터가 투입된 프로젝트는 모두 그래요. 물론, 라인 입사 초기에는 모두 다른 방식 관리하고 있었어요. 깃(Git)을 쓰는 곳도 있고 아닌 곳도 있고요. 프로젝트별로 관리 주체가 달랐고, 테크니컬 라이터는 작업 도구나 사이트 배포 방식에는 관여하지 않았거든요.
전 처음 블록체인 관련 프로젝트에 투입됐어요. 프로젝트가 막 시작된 단계라서 개발자도 이제 막 모인 상황이었죠. 체계적으로 프로세스를 정립하고 만들기 딱 좋은 상황이었어요. 이참에 SSG(Static Site Generation)를 사용해야겠다고 마음먹고 실행에 옮겼죠.
SSG는 마크다운으로 작성한 문서를 웹페이지 파일로 만들어주는 도구예요. 처음 프로젝트를 시작할 때 프로젝트 매니저에게 “CMS(Content Management System)를 쓸 수도 있고 SSG를 쓸 수도 있지만, SSG를 추천한다.”고 말씀드렸어요. 커스터마이징도 훨씬 쉽다고 강조한 덕분인지 잘 먹혀들더군요. 여러 이유를 들었지만 제 입장에서는 SSG를 쓰면 문서 쓰기가 훨씬 편하기 때문이에요.
LG전자에서 오픈소스 CMS를 쓴 경험이 있는데, 페이지마다 일일이 내용을 찾아 바꿔야 하고 버전 관리 기능도 별로여서 불편했거든요. 너무 불편한 나머지 아예 로컬에서 마크다운으로 작성한 다음 CMS 편집기에 맞춰 바꿔서 올리는 방식으로 자체 버전 관리를 했어요. 그와 달리 SSG를 쓰면, 전체 문서 찾아 바꾸기 쉽고, 인터넷이 연결 안 되어 있어도 작업할 수 있고, 깃(Git)에서 버전을 관리할 수도 있어서 편하죠. 버전 관리 할 수 있는 CMS도 있지만, 기능 면에서 깃과 비교할 수 없거든요.
로컬 작업, 전체 문서 통합 편집, 강력한 버전 관리 등 텍스트 기반으로 관리하는 것이 여러모로 효율적이라는 결론에 이르렀죠. 당시엔 “Docs as Code”라는 개념을 알고 결정한 건 아니었지만, 나중에 보니 문서를 다루는 사람들 대부분이 비슷한 고민을 한 끝에 나온 개념이더라고요. 이렇게 가면 좋겠다는 확신이 들었어요.
Q. SSG 방식으로 전환하는 데 팀원이나 협업 구성원의 반대는 없었나요? 관련 구성원을 어떻게 설득하셨나요?
변화를 좋아하는 분들도 있지만, 두려워하는 분도 있었어요. 그래서 SSG로 한 번에 바꾸기는 쉽지 않았어요. 깃을 사용하는 건 다들 익숙해 그 부분은 괜찮아했어요. 하지만 SSG로의 전환은 단순히 문서를 마크다운으로 작성하는 것과는 다르다 보니, 어려워하는 분도 있었어요.
특히, 위키에 있던 사내 문서를 SSG로 전환하려고 할 때는 우려하는 분이 많았죠. 그럼에도 문서를 소비하는 독자 입장에서 이 방식이 더 낫다고 계속 설득했어요. SSG가 작성하는 사람에게만 좋은 도구 같지만, 보는 사람에게도 좋은 점이 있거든요. 좀 더 자유로운 포맷을 제공할 수도 있고, 검색하기도 쉽고, 문서에 포함된 데이터를 자동 분류해 볼 수도 있으니까요. 결국 독자 설문조사를 하고 SSG 방식이 더 좋다는 응답을 근거로 보여줬더니 반대하던 분도 이제는 따르고 있어요. (한편으로는 지지해준 높은 분(?)들 덕분이기도 해요.)
그럼에도 여전히 텍스트 포맷식으로 기술 문서를 작성하는 데 어려움을 겪는 분이 있어요. 그럴 땐 저희 팀에서 문서를 대신 작성해 드려요. “마크다운 힘들어요” 하면 “그럼 정보만 주세요, 저희가 쓸게요”라고 해요. 아직 해법을 찾진 못했어요. 깃이나 마크다운을 어려워하는 분도 쉽게 글을 쓰게 할 방법을 여전히 고민하고 있어요.
Q. 도큐먼트 엔지니어링 시스템을 어떤 방향으로 개선해 나갈 계획인가요?
현재는 여러 SSG 중에서 저희 팀에 가장 잘 맞는 걸 선택해 사용하고 있어요. 저희 팀으로 문서 업무가 들어오면 우리는 이런 솔루션을 써서 문서를 관리한다고 설명하죠. 이제는 저희가 관리하는 프로젝트에 한해서는 점차 그 SSG로 통일이 되고 있어요.
저희 팀이 관리하지 않는 프로젝트는 여전히 각 주체가 자체적으로 관리해요. 이런 경우 저희가 개입하기 어렵기 때문에 저희 문서 엔지니어링 시스템을 패키지처럼 만들어 제공하려고 해요. SSG에 쓰는 플러그인이나 컴포넌트를 하나의 패키지로 묶어서 배포하는 거죠. 혹시 개발팀에서 “이런 걸 하고 싶은데 어떻게 하면 되나요?”라고 물으면, 가이드를 드리고 저희가 만든 SSG 패키지를 받아 바로 적용해 사용하게 하는 거죠.
‘기술 문서’에 대해 문답을 하며 이야기하다 보니 예정된 1시간의 인터뷰가 눈 깜짝할 사이에 끝났습니다. 정은 님과 대화하며 기술 문서를 잘 관리하는 것이 단순한 문서 차원을 넘어 고객과 개발 문화, 더 나아가 조직에 커다란 영향을 준다는 점을 깨달았습니다.
사전 인터뷰에서 미처 나누지 못한 기술 문서화 엔지니어링에 대한 이야기는 11월 COMMIT에서 들을 수 있습니다. 11월 COMMIT에서는 글을 잘 쓰는 방법이 아닌 글을 쓰고 관리하는 전체적인 프로세스와 도구 활용에 중점적으로 이야기합니다. 특히 ‘Docs as Code’를 시작하려는 분이나, 이미 시도하고 있지만 어려움을 겪은 분이 모여 서로의 고민을 나누고 해결책을 함께 모색하는 시간이 되길 바라고 있습니다.
