안녕하세요. LINE Plus Tech Content Strategy 팀 하성창입니다. 저희 팀은 테크니컬 라이터로 구성돼 있으며, LINE Plus에서 개발한 다양한 플랫폼의 기술 문서를 작성하는 한편 사내 용어집 사이트인 Words의 콘텐츠와 LY Corporation Tech Blog의 국문 콘텐츠를 담당하고 있습니다. 이 글에서는 LINE Planet이라는 VoIP 플랫폼의 문서에 싱글 소싱(single sourcing)을 적용해 문서 관리 효율성을 개선한 사례를 공유하려고 합니다.싱글 소싱은 하나의 소스에서 여러 가지 결과물을 생성하는 것을 뜻하는 용어입니다. 문서화에서는 아래와 같은 두 가지를 모두 의미합니다.• 단일 소스에서 여러 포맷(HTML, PDF, EPUB 등)으로 문서를 생성하기. 멀티 채널 퍼블리싱(multi-channel publishing)이라고도 합니다.• 단일 소스에서 맥락에 따라 여러 문서를 생성하기. 여기서 맥락은 문서화 요구사항에 따라 정의할 수 있습니다(배포 환경, 구동 플랫폼 등).예전에는 첫 번째 의미로 주로 사용했으나, 최근에는 두 번째 의미도 포함하여 더 넓게 사용하는 용어입니다. 이 글에서 '싱글 소싱'은 두 번째 의미에 해당합니다.싱글 소싱의 주요 목적은 문서 관리의 효율성과 문서의 품질을 개선하는 데 있습니다.• 문서 관리 효율성 측면에서는 '복사 및 붙여넣기' 작업을 최소화하여 유지 보수를 간소화할 수 있습니다. 콘텐츠를 재사용하여 불필요한 반복 작업을 줄이고 시간을 절약할 수 있습니다.• 문서 품질 측면에서는 단일 출처에서 정보를 가져옴으로써 각각의 문서가 따로 작성되었을 때에 비해 내용이나 스타일 면에서 일관성을 높이고 오류를 줄일 수 있습니다.다음과 같은 경우에 싱글 소싱을 적용할 수 있습니다.• 공통된 부분이 많지만 조금씩 차이가 있는 제품군의 문서를 관리해야 할 때• 소프트웨어 배포 환경에 따라 해당하는 내용의 문서를 만들고 싶을 때싱글 소싱의 주요 기법으로는 다음과 같은 것들이 있습니다.일정한 조건에 따라 콘텐츠 포함 여부를 결정하는 필터링 처리를 의미합니다. 다음과 같은 경우에 활용할 수 있습니다.• 특정 개발 환경에만 해당하는 내용이 있을 때• 멀티플랫폼 문서에서 플랫폼별로 조금씩 차이가 나는 부분이 있을 때예를 들어 'staging' 환경 문서에만 포함되어야 하는 내용을 조건부 콘텐츠로 관리하는 것을 의사코드로 나타내면 다음과 같습니다.값이나 용어를 변수화하는 것을 의미합니다. 다음과 같은 경우에 활용할 수 있습니다.• 특정 기능을 사용하는 데 필요한 최소 SDK 버전을 변수로 관리• 연락처, 고객 지원 채널 등의 URL을 변수로 관리예를 들어 SDK 최소 버전을 변수로 처리하는 것을 의사코드로 나타내면 다음과 같습니다.자주 쓰이는 콘텐츠를 재사용하는 것을 의미합니다. 다음과 같은 경우에 활용할 수 있습니다.• 여러 페이지에 동일하게 나타나야 하는 안내 문구를 재사용• 가이드나 튜토리얼에 반복되는 사전 절차(prerequisites)를 재사용예를 들어 오래된 문서에 대한

Static site generator(이하 SSG)는 웹 문서나 간단한 웹사이트를 만들려는 사람이라면 한 번쯤 들어봤을 단어일 겁니다. 소프트웨어 플랫폼이나 제품 사이트 중에도 SSG로 만든 것이 꽤 많습니다. React는 Gatsby를 쓰다가 2023년에 재단장하면서 Next.js로 갈아탔고, Kubernetes는 Hugo를 씁니다. LINE의 몇몇 기술 문서도 SSG로 만들었습니다. LINE Developers는 VuePress로 만들었고, LINE Blockchain Developers Docs는 Docusaurus로 만들었죠. LINE의 오픈 소스 Promgen은 Sphinx를 썼고요. 와, 여기까지만 해도 SSG가 6가지나 되네요. 하지만 이게 전부가 아닙니다. JamStack 사이트의 SSG 목록에는 무려 355개(2023년 12월 기준)나 있으니까요.SSG로 기술 문서 사이트를 하나 만들어 보려다가도 저 많은 SSG를 보면 엄두가 나지 않을 것 같더군요. 그 막막함을 조금이나마 덜어보고자, 문서 엔지니어로서 팀 공용 SSG를 선정해 사용한 경험을 공유하려고 합니다.왜 팀 공용 SSG를 선정했는지를 이야기하려면 문서 엔지니어링을 소개하지 않을 수 없겠네요. 문서 엔지니어링이라는 단어만 보면 소프트웨어 엔지니어링과 비슷하게 느낄 텐데요. 예, 맞습니다. 소프트웨어 엔지니어링은 "소프트웨어 개발, 관리, 배포 비용을 낮추고 효율과 품질을 높이는 활동"인데, 여기서 "소프트웨어"를 "문서"로 바꾸면 곧 문서 엔지니어링이 됩니다. 문서를 효율적으로 작성, 관리, 배포하고 품질을 높이는 활동이죠.LINE Plus Technical Content Strategy 팀은 꾸준히 문서 엔지니어링을 해왔는데요. 기술 문서 규모가 커지고 문서 사이트 기능이 다양해지면서 2023년부터 내부에 별도 파트를 만들어 문서 엔지니어링 영역을 넓히기로 했습니다. 그중에 팀 공용 기술 문서 작성 프로세스를 수립해 신규 기술 문서에 적용하는 활동도 있었는데요. 그때 팀 공용 SSG(static site generator)를 선정하게 됐습니다.문서 엔지니어는 보통 docs as code 방식으로 기술 문서를 작성합니다. Docs as code는 기술 문서를 소스 코드처럼 취급하고 관리하는 접근법으로, 가장 큰 특징은 Git을 이용한 버전 관리와 테스트, 빌드, 배포 자동화입니다. 개발자 친화적인 환경을 제공해 개발자와 협업하기 쉬운 데다, 버전 관리와 자동화 덕분에 다양한 버전을 동시에 작업하거나 배포할 때도 훨씬 안정적이죠. SSG, 특히 문서용 SSG는 자연스럽게 이 특징을 구현하기에 SSG를 사용하는 것이 곧 docs as code를 도입하는 지름길입니다.다만, SSG가 워낙 다양해서 기술 문서마다 조직 성향이나 작성 시기에 따라 각기 다른 SSG를 쓰더군요. 문서 엔지니어링 파트의 목표는 문서 작업 중 불편한 점을 엔지니어링으로 해결하는 것인데, 똑같은 해결책을 SSG에 맞춰 각각 적용한다면 아무래도 작업 효율이 떨어질 수밖에 없습니다. 그래서 팀 공용

안녕하세요 백엔드팀 허민지입니다. 해당 글은 똑닥 기술 블로그 개편 과정에 대한 기록입니다. 1) 블로그 개편이 불가피했던 이유, 2) 여러 플랫폼과 프레임워크 비교, 3) 블로그를 재정비하며 개선한 점을 상세하게 작성해 보았습니다. 글이 도움이 되길 바라며 가벼운 마음으로 한 번 읽어봐 주시기 바랍니다. 기술 블로그 개편이 필요한 이유 첫 번째 이유는 기술 블로그를 활용하여 더 많은 인재를 영입하기 위함입니다. 기존 기술 블로그의 경우 채용 관련 섹션이 없었으며 블로그 포스트만 올릴 수 있도록 설계되었습니다. 기술 블로그는 기술 관련 글을 올리는 곳이기도 하지만 동시에 한 회사의 개발 문화와 이야기를 나누는 공간이기도 합니다. 많은 분의 기술 블로그 방문은 곧 자연스레 기술 블로그를 운영하는 회사에 대한 관심과 채용 공고 지원으로 이어집니다. 그렇기에 기술 블로그는 더더욱 채용과 떼어 놓고 볼 수 없다고 판단하였습니다. 두 번째 이유는 요즘 유행하는 프레임워크에 비해 기능이 미미하였습니다. 백엔드팀은 Jekyll 프레임워크로 2019년 블로그 신설 후 오랫동안 블로그를 유지보수하지 않고 있었습니다. 또한 팀 내에서 올해 언급된 기술 블로그 개선 사항 및 계획했던 개편, 확장 기능을 모두 추가하면 공사 기간과 사이즈가 점점 커져 갔습니다. 저는 기술 블로그 관리자로서 Jekyll을 커스터마이징하는 데 점점 한계를 느꼈고, 지금 백엔드 팀에게 Jekyll이 최선의 프레임워크인지에 대한 의문이 들었습니다. 결론적으로 저는 여러 조건을 고려했을 때 Jekyll로 하나씩 기능을 추가하거나 수정하는 것보다, 아예 새로운 프레임워크로 재정비하거나 다른 플랫폼으로 이전하는 방향으로 결정하였습니다. 팀 의견을 반영한 기술 블로그 개선점 메모 기술 블로그 플랫폼을 정할 때 고려했던 점 먼저 기술 블로그 플랫폼/프레임워크 교체 시 중요하게 생각하는 부분을 우선 순위를 정하여 나열해 보았습니다: 1. code snippet을 추가하기 쉬운가? 2. 새로운 플랫폼/프레임워크로 이전 시 팀원들이 빠르게 적응할 수 있는가? 3. 글을 작성하기 쉬운가? (a.k.a. 마크다운으로 쓸 수 있는가?) 4. 커스텀 하기 쉬운가? 5. 확장성 있는 플랫폼/프레임워크인가? 6. 어느 정도 고정 관객을 확보할 수 있으면 좋겠다는 바람(욕심) 모든 조건을 만족시키는 플랫폼/프레임워크를 찾기는 어려웠지만 기존 프레임워크의 적합한 대체제를 찾기 위해서는 많은 조건을 고려할 수밖에 없었습니다. 또한 본격적인 개편에 들어가기 앞서 타 기업 기술 블로그를 조사하며 어떤 플랫폼과 프레임워크를 주로 쓰는지 정리해 봤습니다. 많은 기업에서 미디엄과 GatsbyJS를 쓴다는 것을 알 수 있었습니다. 여기에 팀원 한 분이 적극적으로 추천하신 Docusaurus까지 총 3가지 플랫폼/프레임워크를 비교하고 하나를 최종 선택하기로 했습니다. 기술 블로그 플랫폼/프레임워크 비교 1. 미디엄 미디엄은 온라인 출판 플랫폼 중 하나이며 해당 플랫폼으로 많은 기업과 작가들이 본인만의 창작물과 글을 올리고 있