1999년에 출간되어 소프트웨어 개발의 고전으로 불리는 책 ‘실용주의 프로그래머’는 개발도구에 대해 이렇게 말해요.
” 도구는 여러분의 재능을 증폭한다.
도구가 더 훌륭하고 여러분이 더 사용법에 능숙해질수록 여러분의 생산성은 더 높아질 것이다. “
그들의 말처럼 어떤 도구를 쓰는지, 그리고 얼마나 능숙한지에 따라 생산성은 달라져요. 그래서 많은 개발 도구는 활용 방법을 전달하기 위해 노력하고 정보를 공유하는 커뮤니티가 형성되어 있어요. 실제로 세계 최대의 개발 커뮤니티 스택오버플로우(Stack Overflow)가 진행한 개발자 설문조사에 따르면 개발자는 온라인에서 코드를 배우는 방법으로 기술 문서를 가장 많이 선택했어요.
팀 플렉스튜디오는 앱 개발부터 운영 & 배포까지 하나로 가능한 로우코드 앱 개발 도구 ’플렉스튜디오’ 를 만들어요. 그래서 플렉스튜디오 사용자가 더 쉽고 편리하게 학습할 수 있도록 기술 문서를 리뉴얼했어요. 기존 기술 문서의 문제부터 새롭게 달라진 기술 문서의 제작 과정까지 개발자가 몸으로 부딪치며 배운 기술 문서 작성법을 공유할게요.
문제 정의 : 플렉스튜디오 기술 문서, 무엇이 문제였을까?
리뉴얼 전 플렉스튜디오는 ‘사용자가이드’라는 이름으로 노션(Notion)을 활용해서 플렉스튜디오 사용 방법을 설명했어요. 하지만 기술 문서라고 하기에 한계가 있고 불편하다는 사용자의 의견을 들었어요. 마침 팀 전체가 같은 문제에 공감하고 있었어요. 모든 팀원이 모여 기존 기술 문서에 대한 생각을 허심탄회하게 이야기했어요. 부족한 내용과 원하는 정보를 찾기 어려운 문서 구조가 가장 큰 문제로 지적되었어요.
문제를 찾은 후엔 ‘좋은 기술 문서란 무엇일까?’ 공부하며 기존 기술 문서의 강점과 약점 분석, 앞으로 해야 할 일 등을 의논하는 시간을 가졌어요. 무언가를 새로 만든다는 사실이 막막했지만, 그 전에 분명히 해야 하는 일이라는 믿음이 있었거든요.
사용한 도구 : 어떤 도구를 사용할까?
노션으로 기록하는 방법에 한계를 느꼈던 만큼 기술 문서 리뉴얼은 도구를 찾는 일로 시작했어요. 개발자에게 가장 편리한 기술 문서 형태를 찾기 위해 직접 개발하는 방식부터 기술 문서를 작성할 수 있는 다양한 툴을 조사했어요.
깃북(GitBook)을 선택한 이유
깃북(GitBook)이란 누구나 쉽게 문서를 작성하고 이를 쉽게 관리하고 배포할 수 있도록 도와주는 오픈 소스 플랫폼이에요. 플렉스튜디오가 깃북을 선택한 이유는 크게 세 가지예요.
① 편리한 협업 기능
깃북은 여러 사용자가 동시에 문서를 작성하고 수정할 수 있어서 팀 프로젝트에 유리해요. 팀원 모두가 작성하고 리뷰하고 수정해야 했기에 다른 기능보다 특히 협업과 관련된 기능이 중요했어요.
② 간단한 버전 관리
깃(Git)과 통합을 통해 문서의 버전 관리를 쉽게 할 수 있는 점이 좋았어요. 그리고 깃북을 통해 작성된 문서를 쉽게 웹사이트 형태로 호스팅할 수 있고 변경 사항이 있다면 쉽게 업데이트 할 수 있어요.
③ 직관적인 문서 작성과 디자인
일반적인 문서 작성 혹은 마크다운 형식 중 원하는 대로 선택할 수 있기 때문에 간단하고 직관적으로 콘텐츠를 작성할 수 있어요. 그리고 다양한 테마와 플러그인을 사용해서 문서의 디자인과 기능을 쉽게 커스터마이징할 수 있다는 특징이 있어요.
추가로 깃북은 내장된 검색 기능을 통해 문서 내용을 빠르게 찾을 수 있으며 PDF, ePub 등 다양한 형식으로 문서를 출력할 수 있다는 장점도 있는 도구예요.
스토리레인(Storylane)을 선택한 이유
스토리레인(Storylane)은 대화형 데모나 튜토리얼을 제작할 수 있는 SaaS(Software as a Service) 플랫폼이에요. 스토리레인을 사용하면 코드를 작성할 필요 없이 소프트웨어의 기능을 시각적으로 설명하고 시연할 수 있어요. 플렉스튜디오 가이드는 개념과 함께 실습 내용을 설명하는데요. 그때 문서 내에서 스토리레인으로 제작한 튜토리얼로 바로 체험하면 훨씬 더 쉽게 이해할 수 있을 거라고 생각했어요.
문서 작성 & 리뷰 : 기술 문서, 원래 이렇게 어려운 걸까?
가이드 문서를 기획하며 크게 세 가지 기준을 고려했어요.
- 초보자를 위한 기초 지식과 난이도 높은 정보를 모두 담아야 한다.
- 플렉스튜디오의 독자적인 개념과 개념을 쉽게 이해할 수 있는 실습이 있어야 한다.
- 플렉스튜디오의 문서는 가이드와 스크립트 명세서로 나누어 작성한다. 가이드는 플렉스튜디오의 전체 설명과 실습 등을 포함하는 문서이며 스크립트 명세서는 플렉스튜디오의 모든 스크립트와 메서드, 속성에 관해 설명한다.
플렉스튜디오의 문서 작성 방식
100개가 넘는 세부 목차를 정하고 모든 팀원이 참여해 문서 작성을 시작했어요. 기술 문서 작성은 아주 많은 협업이 필요한 작업이었어요. 일단 테크니컬 라이터(해당 목차의 작성 담당자)가 자신이 맡은 부분을 작성해요. 작성할 땐 일관된 형식으로 작성할 수 있도록 용어를 통일해서 정리하고 컨벤션 요소를 정했어요. 목차별로 트레커하는 방식으로 가이드를 사용하는 개발자가 현재 어느 단계에 있는지, 얼마나 진행되었는지 파악할 수 있도록 했어요. 혹은 링크를 통해 현재 설명과 관련 있는 다른 개념으로 건너뛰거나 다시 돌아갈 수 있도록 구성했어요.
작성한 후엔 관련 기능을 개발한 담당자 등 1명 이상의 팀원을 리뷰어로 지정했어요. 각자 작성하고 끝나는 게 아니라 작성한 내용을 리뷰하고 논의를 거쳐 수정하는 과정을 여러 번 반복해야 했기 때문에 시간이 오래 걸렸어요. 하지만 개발한 부분이 각각 다르기에 서로 물어보고 보완하는 과정을 거치면서 훨씬 더 좋은 결과가 나올 수 있었다고 생각해요.
마무리하며 : 앞으로 계속될 기술 문서 업데이트
리뉴얼 과정을 거쳐 플렉스튜디오 가이드 문서가 공개되었어요. 또한 기술 문서를 계속 업데이트하고 발전할 수 있도록 플렉스튜디오만의 방법을 찾아가고 있어요.
① 배포와 연결된 문서 업데이트
플렉스튜디오는 새로운 기능이 자주 출시되는 개발 도구이기 때문에 반드시 꾸준한 가이드 문서 업데이트가 필요해요. 따라서 배포가 마무리되면 문서를 업데이트하는 팀 내부의 절차를 만들었어요.
② 구글 애널리틱스로 사용자 분석
현재 목차 구성과 실습 내용 등은 팀 플렉스튜디오의 가설에 의해 작성되었어요. 따라서 구글 애널리틱스를 통해 가이드 문서의 데이터를 분석한다면 사용자가 우리의 가설과 비슷하게 사용하는지 확인할 수 있을 거로 생각했어요. 어떤 내용에 반응이 많았는지 등 지표를 확인해서 더 편리한 방향으로 수정할 예정이에요.
③ 문서 오류 보고 & 문서 기여
팀 플렉스튜디오는 늘 열린 마음으로 사용자의 의견을 기다리고 있어요. 만약 문서에서 오류를 발견했거나 문서 기여를 통해 가이드 문서에 개발 지식을 나누고 싶으시다면 flextudio@ksystem.co.kr로 메일을 보내 주세요!
