[TW] 테크니컬 라이터와 Git

Krew Insight

[TW] 테크니컬 라이터와 Git

chedda.choi 2023. 4. 5. 10:00

시작하며

안녕하세요. 카카오엔터프라이즈 테크니컬라이팅 팀의 Crystal(김유리)과 Sandy(차신영), Brina(이나영)입니다.

최근 IT 기업의 테크니컬 라이터 영입 공고에서 Git과 Markdown 활용 역량을 우대하는 경우를 많이 볼 수 있습니다. 이러한 추세에는 전광석화처럼 발전하는 IT 기술과 테크니컬 라이터가 단순한 문서 작성자가 아니라는 전제가 깔려있는 것 같습니다.

상대적으로 기술과 제품의 혁신 속도가 더뎠던 과거에는 독자에게 정보를 전달하기 위해 종이나 PDF 매뉴얼을 많이 사용했습니다. 지금도 업계 특성에 따라 종이나 PDF 매뉴얼을 사용하는 곳도 있습니다. 하지만 IT 기업의 경우, 한 번 배포하면 수정할 수 없는 문서 형태는 정보 업데이트 관점에서 적절하지 않은데요. 따라서 IT 업계에서는 일찍이 사용자에게 실시간으로 정보를 전달할 수 있는 웹 형태의 문서 배포 방식이 일반화되었고, 이러한 형태의 문서를 쉽게 관리할 수 있는 Git이 대중적인 도구로 자리 잡았습니다.

본 포스팅에서는 기술문서에 Git을 사용할 때 얻을 수 있는 장점과 테크니컬라이팅 팀에서 Git을 어떻게 활용하고 있는지 소개하도록 하겠습니다.

기술문서와 Git

Git은 코드 변경 사항이나 버전을 관리할 수 있는 분산 버전 관리 시스템(Distributed Version Control System, DVCS)으로, 2005년에 Linus Torvalds가 오픈 소스 프로젝트인 리눅스 커널(Linux Kernel)의 버전 관리를 위해 개발했습니다. 정의만 들어봤을 때 Git을 "개발용"이라고만 생각하시는 분들이 있을 것 같은데요. 하지만 Git은 기술문서 작성과 배포에도 널리 활용되는 도구입니다.

기술문서의 코드화 (Docs as Code)

오늘날 많은 빅테크 기업은 Documentation as Code(이하 Docs as Code) 방식을 채택하고 있습니다.

Docs as Code란 개발자가 코드를 만드는 데 사용하는 것과 동일한 도구나 Workflow(워크플로)를 따라 문서를 작성하고 게시하는 것으로, 문서 작성자와 개발자 간의 공동 작업 환경을 조성합니다. 즉, 문서를 코드처럼 다룰 수 있게 한다는 것이죠. 이는 문서의 버전 관리나 이력 추적, 자동화된 빌드 및 배포, 개발자와 문서 작성자 간의 긴밀한 협업, 코드 및 문서의 일관성을 유지해 문서의 품질을 높이는 데 도움을 줍니다. 구글의 테크니컬 라이터였던 Riona Macnamara가 WRITE THE DOCS NA 2015에서 구글 내 분산된 문서로 인한 문제를 테크니컬라이터 중심의 툴이 아닌, 개발자의 워크 플로나 도구를 활용해 해결했다고 발표하면서 Docs as Code는 순식간에 확산되기 시작했습니다. 상세한 내용이 궁금하시면 아래 영상을 참고해 보시면 좋을 것 같습니다.

WRITE THE DOCS NA 2015에서 진행한 Riona Macnamara의 발표 영상

오늘날의 문서 게시 사이트는 두 가지 방식으로 정리할 수 있습니다. 첫 번째 방식은 구글이나 AWS 같은 빅테크 기업처럼 자사의 문서 아이덴티티에 맞게 웹사이트를 개발하여 문서를 게시하는 것입니다. 각자의 방식으로 문서 사이트를 구축하지만, 데이터베이스(Database)가 아닌 Git 같은 버전 관리 시스템과 정적 사이트 생성기(Static Site Generator)를 사용하여 기술문서를 관리한다는 면에서 공통 분모를 찾을 수 있습니다. 두 번째 방식은 사이트를 직접 개발하기 어려운 경우, Gitbook이나 Read the Docs 등의 상용화된 문서화 툴을 사용하여 문서를 웹에 게시하는 것입니다. 문서를 웹에 게시할 경우에는 마크업(Markup) 언어를 많이 채택하고, 그중에서도 일반 텍스트 기반의 경량 마크업 언어인 마크다운(Markdown)을 널리 사용합니다. GitHub 같은 호스팅 서비스(Hosting Service)에서도 마크다운을 지원하죠.

사실 기술문서 작성에 Git과 마크다운이 널리 사용되기 시작한 시점은 약 10년이 채 안 되었습니다. 2008년 GitHub의 등장으로 많은 개발자가 사용해 대중화되면서, 자연스럽게 IT 기업의 테크니컬 라이터도 Git을 접하고 문서 작성 및 배포 도구의 하나로 사용하게 된 것 같습니다.

Docs as Code를 채택한 기업은 먼저 마크다운과 같은 마크업 언어로 문서를 작성합니다. 그다음 정적 사이트 생성기를 통해 문서를 HTML 같은 정적 파일로 변환하고, 이렇게 생성된 HTML 문서를 직접 운용하는 서버나 호스팅 서비스를 이용해 업로드하여 게시합니다. 저희도 초안 작업 후 Git과 정적 사이트 생성기를 활용해 기술문서를 게시하고 있는데요. 좀 더 자세히 설명해 드리면 개발자 문서는 Jekyll, Hugo 등과 GitHub을 사용하여 자체 개발 문서 사이트인 Kakao i 기술문서에 게시하고, 카카오워크 사용자 가이드는 Git에 기반한 문서 상용 플랫폼인 Gitbook에 게시하고 있습니다.

Git의 장점

Git을 사용해서 기술문서를 작성하면 많은 장점이 있는데요. 대표적인 장점을 살펴보도록 하겠습니다.

(1) 버전 관리(Version Control)

Git은 코드 변경 이력을 모두 커밋(Commit)으로 기록해 버전을 만들어 영구 저장합니다. 기술 문서 작업 시 여러 사람이 수정한 문서를 버전으로 쉽게 비교할 수 있습니다. 코드를 수정했는데 막상 소스 코드가 정상적으로 작동하지 않아 수정한 내용을 취소해야 하는 경우도 있습니다. 하지만 코드를 하나씩 비교하면서 수정 사항을 찾는 것은 거의 불가능하죠. 이때 Git이 저장한 버전 중 하나로 쉽게 되돌아갈 수 있습니다.

(2) 백업(Backup)

앞서 말했듯 Git은 커밋으로 이전의 코드를 모두 기록하기 때문에, 문서가 유실된 경우에도 쉽게 복구할 수 있습니다. 특정 코드가 필요할 때 그 코드가 커밋된 버전으로 롤백(Rollback)할 수 있죠. 노트북에 실수로 커피를 쏟아 파일이 모두 사라져도 원격 저장소인 GitHub에 남아있어 전혀 걱정할 필요가 없습니다. 저희는 필요한 경우에 복구할 수 있도록 특정 커밋이 있는 브랜치(Branch)를 생성하여 관리하고 있습니다.

(3) 협업(Collaboration)

Git에서 독립적으로 코드를 작성하거나 다른 작성자와 파일을 주고받으며 작업할 수 있습니다. Git은 누가 어느 부분을 어떻게 수정했는지 기록하므로, 오류 발생 시 원인을 파악하거나 해당 부분의 작성자와 논의하기도 수월합니다. 개발자 또한 대부분 Git에 익숙하기 때문에 기술문서 작업 과정에서 보다 원활한 협업이 가능합니다.

(4) 자동화된 배포(Deployment automation)

Git을 활용해 구축한 CI/CD의 자동화된 통합 및 배포 환경에서는 테크니컬 라이터도 쉽게 문서를 배포할 수 있습니다. 이 과정에서 개발자에게 문서 배포를 부탁하지 않아도 됩니다.

Continuous integration(CI)이란 코드 수정 사항이 정기적으로 빌드 및 테스트를 거쳐 리포지터리(Repository)에 병합되는 것을 말하고, Continuous deployment(CD)란 병합된 코드가 자동으로 배포되는 것을 의미하는데요. 일반적으로 리포지터리의 브랜치에 문서 수정 사항을 병합하면, 빌드가 시작되고 문서가 배포됩니다. CI/CD를 통해 빠르고 신속하게 문서를 배포할 수 있고, 이렇게 시간과 자원을 절약하여 문서 품질을 높이는 데 집중할 수 있습니다.

Git으로 기술문서 작성하기

앞서 저희 팀에서 Git을 활용해 기술문서를 게시한다고 했는데, 구체적으로 어떻게 문서를 작업하고 게시하는지 소개하도록 하겠습니다.

Step 1. 초안 작성하기

저희 문서화 프로세스에서는, 먼저 담당자가 문서 초안을 작성하고 해당 초안을 테크니컬 라이터가 리라이팅(Rewriting)합니다. 이때 초안은 구글 독스나 위키를 활용해 작성합니다. 앞서 Git으로 문서를 작성하면 좋다고 말했는데, 왜 초안은 Git으로 작업하지 않을까요?

사실 Git에서 초안 작성부터 게시까지 할 수 있으면 좋겠지만, Git은 피드백을 쉽게 주고받는 기능이 없어 의사소통이 다소 불편합니다. 물론 Commit 메시지로 의견을 남길 수는 있지만, 이 역시 편한 방법은 아닙니다. 그래서 실시간으로 메모를 남기고 확인할 수 있는 구글 독스나 위키에서 초안을 작성합니다. 이 점은 《Docs Like Code》라는 책에서도 잘 설명되어 있는데요. 이 책의 저자이자 테크니컬 라이터인 Anne Gentle은 문서 피드백이 많을 경우에는 의견을 공유할 수 있는 구글 독스 같은 더 유연한 플랫폼에서 협업하는 것이 좋은 방법이라고 소개하고 있습니다. 또한 idratherbewriting.com 운영자이자 구글의 테크니컬 라이터 Tom Johnson도 Version control systems (such as Git)이라는 포스팅에서 대부분의 개발자는 Git에서 문서를 관리하는 것에 익숙지 않기 때문에, 구글 독스나 위키에서 초안을 작성하는 방법이 더 빠르고 효율적이라고 설명하고 있습니다.

단, 이 방식에는 구글 독스나 위키에 작성한 초안 문서와 기술문서 사이트에 게시되는 최종본으로 문서가 이원화된다는 이슈가 있는데요. 문서 게시 후 반드시 초안 문서도 업데이트하여 최종본과 초안 모두 최신 상태로 유지하는 것이 중요합니다. 추후 추가적인 업데이트 작업을 해야 할 때, 초안과 최종본이 다르면 작업자에게 혼란을 줄 수 있기 때문입니다.

Step 2. 이관하기

초안이 완료되면, 로컬 저장소(PC)에서 Visual Studio Code 같은 코드 편집기를 사용해 마크다운 파일로 작성한 후, 원격 저장소인 GitHub에 이관합니다. 이때 충돌을 최소화하기 위해서 팀에서 정한 Git 워크플로를 준수합니다.

저희는 문서 작업 시 배포 브랜치(Main)를 남겨두고 각자 작업 브랜치를 생성해 서로 다른 챕터나 문서만 작업합니다. 같은 문서를 동시에 작업하는 경우는 극히 드뭅니다. 이러한 워크플로에서는 병합(Merge) 시 충돌이 거의 발생하지 않아 팀과 함께 문서를 작업하기에 수월합니다. 또한 PC에서 정적 사이트 생성기로 로컬 버전의 기술 문서 사이트를 빌드해 작업 상태를 확인하면서 문서화를 진행합니다. 문서가 최종 확정되면 리뷰를 위해 작업 브랜치의 최종본을 Sandbox 브랜치에 병합합니다.

Step 3. 리뷰하기

이제 Sandbox 브랜치에서 문서 이해관계자들과 함께 최종 리뷰를 진행합니다. Sandbox 브랜치는 리뷰용 기술문서 사이트를 빌드 및 배포하는 브랜치로, 웹에 게시될 문서의 모습을 미리 확인할 수 있습니다. 리뷰 중 수정 사항이 발생하면 다시 각자의 작업 브랜치에서 수정한 후 Sandbox 브랜치에 반영하죠. 이때 Git의 진가가 발휘됩니다. 여러 작업자가 구석구석에서 문서를 수정하기에 작은 변화를 알아채기 쉽지 않은데요. Git에서는 원본과 변경된 부분을 빠르게 확인할 수 있어, 다른 누군가가 잘못 수정한 부분도 쉽게 찾아내 정정할 수 있습니다.

Step 4. 게시하기

최종 리뷰까지 완료되면, 문서를 웹상의 기술문서 사이트에 게시합니다. GitHub에서 Sandbox 브랜치를 Main 브랜치로 병합하기만 하면 자동으로 서버에서 사이트가 빌드됩니다. Docs as Code가 유용한 이유 중 하나인데요. 이렇게 배포가 자동화되어 있기 때문에, 개발자에게 따로 배포를 요청하지 않아도 됩니다. 그렇기에 테크니컬라이터는 문서 자체에 더욱 집중할 수 있고 작업 효율성도 높일 수 있죠. 마지막으로 게시된 기술문서를 리뷰하면 모든 작업이 마무리됩니다.

포기할 수 없는 Git

하지만 이런 작업 프로세스에는 다소 어려움이 있습니다. Git이 아닌 위키나 구글 독스로 초안을 작성하다 보니, 급한 변경 사항은 GitHub에 바로 반영하는 경우가 생기는데요. 이 경우, 초안과 GitHub의 싱크(Sync)가 깨지기 때문에, 변경 사항을 동일하게 관리해 줘야 하는 번거로움이 있습니다. Git으로 의사소통하기도 쉽지 않고요. 간혹 팀 내 Git 워크플로를 실수로 지키지 않았을 때, 브랜치 병합 시 충돌이 발생하여 작업한 부분이 없어지는 경우도 발생합니다.

하지만 이러한 이유로 Git을 멀리할 필요는 없습니다. 앞서 말했듯이 문서의 변경 사항을 쉽게 확인할 수 있고, 문서가 유실될 경우에는 복원이 가능하기 때문입니다. 여러 사람이 한 곳에서 모든 문서를 작업하고 관리할 수 있어 효율적인 협업도 가능합니다.

또한, 협업 중 충돌이 발생하더라도 원인 파악과 대응이 용이합니다. 충돌이 발생하면 코드 편집기에서 충돌 전후의 코드를 비교하여 수습할 수 있게 도와주고, Git 자체에도 충돌을 해결할 수 있는 명령어가 존재합니다. 처음에는 이런 오류를 해결하기 어려울 수 있지만, 오류 케이스를 하나씩 풀어가면서 Git에 조금씩 익숙해질 수 있습니다.

작업 환경 설정도 간단합니다. 새로운 팀원이 들어왔을 때, Git과 코드 편집기만 있으면 바로 작업이 가능합니다. 별도로 라이선스를 구매하는 등의 과정이 필요하지 않아 누구나 쉽게 작업을 시작할 수 있습니다. 마지막으로 Git을 사용해 문서를 만들고 게시하는 워크플로는 개발자들의 워크플로를 많이 반영했기 때문에 작성자와 개발자 간의 공동 작업이 수월합니다.

마치며

지금까지 테크니컬라이팅 팀에서 기술문서 작업에 Git을 함께 사용하는 방법을 살펴보았습니다. 오늘 전하고자 한 이야기는 ‘Git을 사용하자’가 아니라 ‘기술문서도 코드처럼 버전 관리 시스템이나 플랫폼을 활용해 관리할 수 있고, 이때 Git을 사용하면 크게 도움이 된다'는 것입니다. 물론 기술문서를 게시하기 위해 Git이나 정적 사이트 생성기를 사용하는 방식이 처음에는 생소할 수 있습니다. 그렇다고 할지라도, 일단 Git을 사용해 기술문서를 배포하는 방식에 적응하면 효율적인 작업이 가능해 더욱 문서 자체에 집중할 수 있습니다. 직접 사이트를 개발하든, 아니면 Gitbook과 같은 상용 소프트웨어를 사용하든 IT 기업의 테크니컬 라이터에게 Git은 이제 피할 수 없는 트렌드이기도 합니다.

Git을 사용하면 개발자에게 따로 부탁하지 않고 테크니컬 라이터가 직접 문서 배포까지 할 수 있어 만족스럽기도 합니다. 그렇지만 결국 문서는 코드가 아니기 때문에, 테크니컬 라이터로서 기술문서를 코드화하는 데 집중하기보다는 ‘효율적인 문서 관리와 협업을 바탕으로 더 좋은 기술문서를 배포하기 위해 Git을 활용한다’라고 생각해 주시면 좋을 것 같습니다. 그럼 저희는 다음 포스팅으로 다시 찾아뵙겠습니다. 감사합니다.

참고 문헌

[1] Anne Gentle. Docs like Code. Lulu.com. 2017

[2] 이고잉, 고경희. Do it! 지옥에서 온 문서 관리자 깃&깃허브 입문. 이지스퍼블리싱. 2019

[3] Travis Swicegood. Git, 분산 버전 관리 시스템. 인사이트. 2010