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. 미디엄 미디엄은 온라인 출판 플랫폼 중 하나이며 해당 플랫폼으로 많은 기업과 작가들이 본인만의 창작물과 글을 올리고 있