젯브레인스 문서화 도구 ‘라이터사이드’ 뜯어보기

개발자의 커뮤니케이션

개발자에게 커뮤니케이션은 중요한 역량 중 하나입니다. 여기서 소통의 대상은 보통 같은 조직의 또 다른 개발자이거나, 혹은 협업하는 비개발직군을 생각해볼 수 있는데요. 사실 개발자는 작업 결과물을 사용하는 “고객” 또는 또 다른 “개발자”를 포함해 “조직 외부의 사람”과도 소통을 해야 하는 경우가 있습니다.

이러한 소통 중 하나는 작업 결과물을 설명하는 문서로 이뤄지게 되는데, 개발자가 만들어둔 API를 사용하는 방법을 “설명”하는 “API 가이드”가 하나의 예시라 할 수 있습니다.

글에 기반한 개발자의 커뮤니케이션에는 API 가이드 외에도 SDK나 제품 설명서, 기술 지침서, 설치 안내서 그리고 조직 구성원을 위한 위키 문서 등 다양한 종류가 있지만 이들을 모두 “기술 문서"로 표현하겠습니다.

기술 문서의 특징

위에서 보여드린 예시처럼 기술 문서는 글쓰기의 결과이지만, 보통의 글쓰기와는 몇 가지 다른 점이 있습니다.

1. 명확한 대상 독자: 보통의 글쓰기는 불특정한 사람을 대상으로 작성되지만, 기술 문서는 보통 ① 어느 정도 맥락을 이해하고 있는 ② 개발자가 ③ 개발에 활용하기 위한 목적을 가지고 글을 읽는다는 특징이 있습니다.
2. 글의 목적: 그러다 보니 보통 (수필과 같은) 글쓰기는 정보 전달 외에도 감정 표현이나 설득, 창작과 같은 다양한 목적을 위해 작성되며 작가의 개성이나 문체, 톤 등의 영향을 받지만, 기술 문서는 정보 전달이 목적이라 ①명확 ②간결, ③일관된 내용의 글쓰기가 필요합니다.
3. 글의 구조: 보통 글은 기-승-전-결과 같은 스토리텔링을 위한 구조를 가질 수 있지만, 기술 문서는 논리 / 계층적인 구조를 가지며 특히 그림과 표, 예시 코드 등이 포함된다는 차이가 있습니다.
4. 정보의 갱신: 보통 글은 글의 내용이 바뀔 필요가 거의 없지만, 기술 문서는 시간이 지나면서 기능이 추가되거나 변경 / 삭제될 수 있기에 이를 반영하는 적절한 유지보수가 필요합니다.
5. 글의 배포: 보통 글은 독자가 구매를 하는 것으로 도서나 전자책과 같은 형태로 전달될 수 있지만, 기술 문서는 사용자가 비용 없이 접근할 수 있어야 하며 보통은 온라인 / 웹페이지의 형태로 제공됩니다.

이처럼 기술 문서의 “보통의 글쓰기와 다른” 특징 때문에 개발자들이 기술문서를 작성하기가 조금 더 까다로워 많은 개발자들이 어려워할 수 있고, 이를 위해 테크니컬 라이터(TW)나 데브렐(Developer Relation) 같은 전문가의 도움을 받기도 합니다.

그런데 최근, 데이터 직군에게는 파이참(Pycharm)으로 알려진 젯브레인스(Jetbrains)에서, “기술 문서를 작성하기 위한 목적의 전용 IDE”, 라이터사이드(Writerside)를 출시했습니다. (엄밀히는 최근에 “얼리 액세스로 공개” 되었습니다.)

이번 글에서는 ①라이터사이드의 특징 및 장단점 소개 ② 실제로 라이터사이드를 활용하여 “아주 작은” 기술 문서를 만드는 방법과, 그리고 ③젯브레인스가 라이터사이드를 만들게 된 이유를 “상상”해보겠습니다.

라이터사이드의 특징

라이터사이드를 소개하는 문장 중 하나는 “The most powerful development environment - now adapted for writing documentation”입니다. 라이터사이드는 개발자들이 사용하는 (젯브레인스의) “파이참”, “인텔리제이(IntelliJ)” 같은 IDE에 플러그인 형태로 추가하여 사용하거나, 저처럼 다른 IDE를 사용하는 경우 독립적인 프로그램으로 설치하여 사용할 수도 있습니다. (라이터사이드를 사용하기 위한 별도의 비용은 없습니다)

라이터사이드의 가장 큰 특징은 기술 문서 작성에 “Docs-as-code”라는 개념을 사용할 수 있다는 것입니다. 이는 문서 작성 프로세스에 소프트웨어 개발 프로세스를 적용하는 것으로, 다음과 같은 특징을 갖습니다.

앞서 기술 문서의 특징 중 하나로 “정보의 갱신”을 설명했는데, 버전 관리를 위한 깃(Git), 내용을 웹페이지로 만들어내는 통합 빌드 도구, 레이아웃을 만들어내는 기능 등을 제공하기에 기술 문서의 내용 자체에만 (콘텐츠) 집중할 수 있다는 특징이 있습니다.

한편 라이터사이드에서 만들어내는 콘텐츠는 기존에 “동일한 퀄리티와 스타일을 유지하기 위해" 많이 쓰이는 마크다운(Markdown)이나 XML, 그리고 다이어그램을 위한 머메이드(Mermaid), 수식을 위한 레이텍(LaTeX)을 함께 사용할 수 있습니다.

크게 체감될 일은 많지 않겠지만, “코드 리뷰"처럼 콘텐츠의 품질을 검토하고 개선할 수 있는 기능도 제공합니다.

마지막으로 라이터사이드를 조명해볼 만한 특징은 기술 문서를 작성하기 위한 템플릿을 제공한다는 것입니다. 물론 자주 쓰는 형식의 템플릿을 직접 만들어 사용할 수도 있습니다.

라이터사이드의 장단점

실제로 라이터사이드를 사용하여 가벼운 기술 문서를 만들어보면서 느꼈던 장단점은 다음과 같습니다.

1. 젯브레인스의 IDE에서 제공하는 기능들을 추가 비용 없이 활용할 수 있습니다. 특히 다른 IDE를 사용하고 있어 제공되는 기능에 익숙하다면 더 효과적일 수 있습니다.
2. (마크다운과 XML로) 기술문서를 새롭게 작성할 수도 있지만, 기존에 만들어둔 기술 문서를 라이터사이드에 가져와(Import) 변환하는 기능도 제공합니다.
3. 기술 문서의 결과물을 AI를 활용하여 검색할 수 있도록 하는 서비스인 “알골리아(Algolia)”의 검색엔진에 반영할 수 있습니다. (정확히는 모르지만 엘라스틱서치와 유사한 역할을 한다고 이해했습니다.)
4. “Docs-as-code”를 활용하는 만큼 기술 문서의 결과물을 (깃허브 페이지 등) 자체 서버를 사용하지 않고도 별다른 비용 없이 제공할 수 있습니다.
5. Code snippet, Glossary (용어사전), 다운로드 가능한 예시 리소스 파일, 여러 버전에 대한 문서, 커스텀 가능한 디자인 등의 기술 문서를 위한 여러 세부 기능을 제공합니다.

한편 아래의 내용은 사람에 따라 어려움을 느낄 수도 있습니다.

1. “Docs as code”가 효과적인 방법론이긴 하지만, 여전히 개발자가 아니라면 (예를 들어 TW, DR, PM) 기술 문서를 코드처럼 프로젝트로 관리하고 배포하는 과정이 어렵게 느껴질 수 있습니다.
2. 기존에 기술 문서로 활용할 수 있는 Google Docs, Gitbook, Notion, Dropbox Paper, Quarto 등의 방법과 비교해보면, 라이터사이드가 여러 기능을 제공하는 것은 맞지만 조직의 상황에 따라서는 “닭 잡는데 공룡 잡는 칼을 쓴다”는 느낌을 받을 수도 있습니다.
3. 아직 라이터사이드의 공식 문서에서는 한국어를 지원하지 않기에 IDE 특유의 학습 곡선을 더욱 가파르게 합니다.

라이터사이드 사용 방법 소개

(라이터사이드를 사용해 만들어진!) 라이터사이드의 공식 문서를 기반으로 기술 문서를 만드는 방법을 소개합니다. Docs-as-code의 관점에서 기술 문서는 프로젝트-토픽-콘텐츠라는 3개의 계층으로 구성됩니다.

프로젝트는 라이터사이드를 설치 후 New project / Starter project로 만들 수 있으며, 토픽은 프로젝트에서 기본으로 제공하는 Default-topic.md를 편집하거나, 템플릿 혹은 비어 있는 내용을 추가할 수 있습니다.

콘텐츠의 내용을 작성하는 것은 개발자들에겐 익숙할 README.MD나 비개발자들에게도 익숙할 “노션"을 사용하는 것처럼 마크다운으로 작성할 수 있지만, 마크다운에 대한 소개를 이 글에서 다루진 않습니다.

한편 기술 문서에 어떤 내용을 채울 것인가를 설명하는 것은 정말 어렵기 때문에, 몇몇 참고할 수 있을 만한 링크를 첨부하겠습니다.

• 넷마블 테크니컬 라이터로 일한 8개월의 회고
• 기술 문서 작성 5단계
• 마이크로소프트 style guide
• 구글 Technical writing course

이어서 예시 프로젝트로 만든 기술 문서를 독자들에게 웹으로 배포하는 방법을 소개하겠습니다. 배포에는 여러 방법이 가능하지만 개인적으로 익숙한 깃허브 페이지 방법을 소개합니다. (이를 위해 리포지토리는 새롭게 만들었고, 콘텐츠는 제공된 Default-topic.md 의 내용을 그대로 사용하였습니다.)

만약 커맨드 기반의 깃 작업이 익숙하지 않다면, 깃허브와의 편한 연동을 위해 프로젝트 생성을 할 때 “버전 관리에서 가져오기"를 사용하여 URL을 그대로 붙여넣는 것을 권장합니다.

이렇게 생성된 프로젝트에는 기본 템플릿을 제공하지 않기 때문에 Add documents를 사용하여 토픽을 추가합니다. 여기서 지정해야 할 것은 토픽에 보이는 이름인데 (예시의 경우 First Topic), ID는 입력한 이름에 따라 자동으로 생성되며 (ft) 그 외의 옵션은 설정하지 않아도 무방합니다.

라이터사이드는 IDE로써 프로젝트의 변경된 내용을 깃허브에 바로 반영시킬 수 있다는 특징이 있습니다. 이를 반영한 커밋을 제출한 다음, 깃허브 액션으로 깃허브 페이지를 만들기 위해 워크플로우 설정을 해야 합니다.

워크플로우 설정을 위해서는 리포지토리에 “.github/workflows/deploy.yml” 파일을 만들고, 내용을 라이터사이드에서 제공하는 템플릿으로 복사한 다음, env의 내용을 앞서 만든 인스턴스에 맞게 수정합니다.

이후 페이지를 배포한다면 다음과 같이 웹에 배포되는 기술 문서를 확인할 수 있으며, (이 주소에서도 확인 가능합니다) 이전에 제가 주로 사용하던 pkgdown이나 quarto page와는 또 다른 느낌을 주기도 합니다.

젯브레인스는 왜 라이터사이드를 만들었을까?

개인적으로는 라이터사이드가 기술 문서 제작을 위한 여러 기능을 제공하는 좋은 IDE이지만, 콘텐츠 제작 이후에 배포 과정에서 장벽이 조금 있어 비개발직군까지 범용적으로 사용하기엔 조금 어려움이 있겠다는 생각이 들었습니다.

심지어 라이터사이드는 젯브레인스의 다른 프로덕트와는 다르게 라이센스 비용을 필요로 하지 않아 수익이 나기가 더더욱 어려운 프로덕트입니다. 이 점이 더더욱 젯프레인스가 왜 이 프로덕트를 만들었는지를 고민하게 했습니다.

기술 문서 작성을 다루는 다른 도서 <Docs for Developers>의 내용을 일부 인용하면, 기술 문서를 만드는 과정은 아래와 같이 4개의 단계로 나눠볼 수 있습니다.

이 중, 기술 문서를 어떻게(How) 작성하고 독자에게 공유할 것인가를 다루는 “작성”과 “배포”보다도 ‘어떤(What) 내용을 왜(How) 기술 문서로 작성할 것인가’라는 “기획”과 “피드백"의 단계가 더 중요하다고 개인적으로는 생각합니다.

즉 라이터사이드는 기술 문서 작성에서 “핵심이 되는” 부분을 해결하는 프로그램이라기보단, 과정을 보조하는 프로그램으로 볼 수 있습니다. (심지어 기능은 조금 떨어지지만 더 리소스를 들이지 않고 편하게 쓸 수 있는 프로그램도 많이 있습니다)

(정확한 이유는 당사자만이 알겠지만) 젯브레인스가 페인 킬러도 아닌, 수익 모델도 불분명한 프로덕트를 만든 이유를 추측해보면 다음과 같습니다. 

1. 회사의 방향: 

젯브레인스는 개발자의 생산성을 돕는 것이 목표로 하는 조직입니다. 흔히 PM과 같은 비데이터 직군이 “데이터 리터러시”를 활용해서 생산성을 더 올린 것처럼, 라이터사이드는 개발자들이 “커뮤니케이션 리터러시"를 활용해 생산성을 더 올리게 하는 방향의 프로덕트로 볼 수 있습니다.

적절한 기술 문서가 IT 서비스의 고도화에 얼마나 중요한지에 대해서는 이미 국내의 많은 조직들도 알고 있고, 실제로 개발 블로그와 공식 기술 문서를 운영하고 있기도 합니다.

그렇지만 만약 전문 데브렐이나 테크니컬 라이터를 운영할 수 있는 단계의 조직이 아니라면 이러한 “개발자의 커뮤니케이션”을 개발자들이 해야하는데, (오히려 바람직하다고 생각합니다) 젯프레인스가 ‘이를 위한 프로그램을 만든 것이 아닐까?’라는 생각이 들었습니다.

2. 생성형 AI의 발전

챗GPT(ChatGPT)와 같은 생성형 AI를 이제는 누구나 쉽게 사용할 수 있는데, 이는 기술 문서 작성의 기획과 피드백에 큰 도움을 줄 수 있습니다. 이를 고려하면 젯브레인스가 아래 같은 그림을 상상한 것이 아닌가 하는 생각도 해볼 수 있습니다.

젯브레인스에서 기획과 피드백을 제공하는 생성형 AI도 서비스할 수 있다면 더 좋았겠지만, 그런 서비스는 대기업에서도 쉽게 만들기 어렵다는 점을 고려해보면 기존에 IDE를 잘 만들던 역량을 작성과 배포를 돕는 IDE에 선택과 집중하는 것이 좋을 수 도 있습니다.

3. IDE 시장

스택오버플로우(Stackoverflow)의 개발자들을 대상으로 이뤄진 설문조사에 따르면, 최근의 IDE 서비스 점유율은 마이크로소프트가 “압도적으로” 차지하고 있습니다. (Android studio 같이 “특정 언어”에 한정된 IDE를 제외하면 개발의 많은 비율을 차지하는 웹 개발은 VS Code가 가져간다고 볼 수도 있습니다.)

이에 IDE를 주력으로 서비스하는 젯브레인스의 입장에서는 “커뮤니케이션 리터러시"를 필요로 하는 개발자나, 문서 작성을 전문적으로 하는 데브렐 직군을 대상으로 라이터사이드를 제공하고, 그 결과 다른 젯브레인스의 서비스와 IDE로도 유입되는 것을 기대하는 새로운 시장을 개척했다고도 볼 수 있습니다.

VC 애널리스트 알렉산드르 듀에즈(Alexandre Dewes)의 서브스택(Substack)을 인용하면, 단순히 IDE 외에도 생성형AI로 개발자 생산성 향상을 목표로 하는 여러 스타트업들이 최근 들어 많이 등장한 만큼 이들과 차별할 포인트가 필요했고, 그 결과 “또 다른 개발"인 기술 문서를 타깃으로 한 것은 아닐까요?

정리

이번 글에서는 개발자의 커뮤니케이션의 관점으로 보는 기술 문서, 그리고 기술 문서의 특징과 이를 만들 수 있는 새로운 IDE인 라이터사이드를 활용하여 문서를 만드는 과정, 그리고 프로덕트 관점에서의 라이터사이드를 간단히 짚어봤습니다. 아직은 생소한 개념들이지만 (특히 작은 단계의 조직에서는 더욱) 개발자와 개발 조직의 성장에 크게 도움이 될 수 있는 내용들이기에 한번 시도해보는 것을 권장드립니다.

요즘IT의 모든 콘텐츠는 저작권법의 보호를 받는 바, 무단 전재와 복사, 배포 등을 금합니다.