Introduction

일반적인 SW 개발 프로젝트는 진행되는 과정에서 문서가 생산됩니다. 서비스 기획서, 디자인 가이드, API 문서, 인터페이스 정의서 등 SW 개발의 거의 모든 단계에서 각자의 목적에 맞는 문서가 작성됩니다. 이들 문서는 인쇄물 생산을 위해 워드프로세서로 작성되기도 하고, 프리젠테이션을 위해 프리젠테이션 SW로 생산되기도 합니다. 특히 다수의 구성원이 함께 SW를 만들기 위한 도구로서의 문서는 실제 코딩을 위한 참조 과정이 간결해야 하며, 문서에 언급되는 코드가 복사/붙여넣기 에 용이해야 합니다. 다수의 개발자가 동시에 문서를 작성/수정이 가능해야 하며 이 과정에서 문서 내용이 오염될 수 있는 가능성을 최대한 줄여야 합니다. 작성되는 툴을 구성원 모두가 숙지해야 하는것도 당연합니다.

본 포스트에서는 너드팩토리에서 공식 Jekyll 기반 문서를 사용하기 까지의 과정과 각 단계별 변경에 대한 의미를 짚어 보고자 합니다. 지난 포스트에서 다루었던 Jekyll 방식의 블로그 플랫폼을 개발 문서로 활용하기 위해 고민했던 내용들, SW 개발문서의 개념적 정리, Google Docs 부터 발전한 너드팩토리의 개발문서 플랫폼 등의 내용을 포함했습니다.

Concept

무언가 변화가 필요할 때 자신만의 기준을 가지고 판단한다면 실패 확률이 줄어든다고 생각합니다. SW 개발을 위한 문서가 컨셉은 아래와 같이 정리할 수 있습니다.

1. 버전관리 필요

엉켜버린 그물과 꼬여버린 GIT 버전 의존성의 관계

SW 개발은 최소 1명에서 많게는 수천명에 이르기까지 참여 인원이 많아질 수 있습니다. 이에 따라 SW 코드와 함께 문서 또한 버전관리에 신경을 써야 합니다. 일례로 API Response 가 수정되었으나 문서에 반영이 되지 않거나 누락될 경우 개발자가 코드를 재작성해야 하는 일이 벌어집니다. 자원이 낭비가 발생하게 됩니다. 어부들이 출항 전에 그물을 정비하지 않으면 출항 후 어업을 포기해야 하는 일이 발생할 수 있듯이 SW 문서에서도 버전관리의 과정은 필수요소라고 할 수 있습니다.

2. Code 의 존재

SW 문서에는 코드가 등장합니다. 코드는 프로그래밍 언어 별로 다양한 문법과 양식이 존재합니다. 정해진 룰을 철저히 지킨 코드는 개발자가 코드를 읽는 시간을 현저하게 줄여 줍니다. 대개 프로그램 코드는 코드 편집기에서 양식을 지켜 코딩되지만 이를 문서에 동일한 양식으로 옮기는것은 쉽지 않은 작업 입니다. 다행히 문서에 프로그램 코드를 표현하기 위한 다양한 방법이 존재하며 작성하는 과정도 어렵지 않습니다.

3. 성능

SW 프로젝트의 규모에 따라 문서의 크기도 급격히 커질 수 있으며 수십~수백 페이지까지 불어나는 것은 일도 아닙니다. 또한 작성자가 많아질수록 분량이 늘어나는 속도가 빨라집니다. 문서 편집기 혹은 뷰어에 따라 문서의 분량이 많아지면 성능이 저하되는 경우가 많습니다. 많은 분량으로 인해 문서를 조회하는 시간이 길어지게 되면 작업 효율이 떨어지며 문서를 조회하는 구성원의 스트레스 지수도 상승합니다.

4. 접근성

SW 문서는 개발자 외에도 다양한 직군의 구성원 들이 조회할 수 있습니다. 하지만 문서를 조회하는것 조차 특정 전문지식을 요구하는 경우 해당 문서는 접근성이 떨어진다고 볼 수 있습니다. 이러한 상황은 특정 직군의 작업 효율성을 높일 수 있지만 조직 전체적으로 볼때에는 효율이 오히려 떨어지는 상황이라고 볼 수 있습니다.

History

서두에서 언급했듯 너드팩토리에서 사용핸 개발문서 플랫폼은 지속적으로 구성원의 요구에 따라 변화해 왔습니다. 현재 너드팩토리에서 사용중은 환경은 플랫폼 측면에서 세번째 시도입니다. 이러한 변화들을 아래에 설명했습니다.

너드팩토리 개발문서 플랫폼의 변천사

1. Google Docs

Google Docs 를 활용했던 개발 문서

구성원 간의 문서 공유를 위해 너드팩토리의 초기 문서 플랫폼을 Google Docs 를 사용했습니다. Google Docs에서 기본적으로 제공하는 편집자간 실시간 문서 반영, 댓글/토론 기능 등 유용한 기능이 많아 적극적으로 활용했습니다. 하지만 문제는 성능과 코드 측면에서 발생했습니다. 일반 문서편집기 라는 특성 상 프로그램 코드를 정해진 양식으로 작성하기 힘들었고, 이를 활용하기 위해 편집시간이 별도로 들어가는 등 코드 활용성 측면에서 비효율적 이었습니다. 또한 문서가 길어지면서 문서 로드, 페이지 이동 등의 성능이 급격히 떨어지면서 많은 낭비를 초래했습니다.

2. Markdown with Bitbucket Repository

Bitbucket을 활용했던 개발 문서

이에 Google Docs 에서의 단점을 커버하기 위해 Markdown으로 작성하여 성능을 제고하고 코드 사용성을 높이며 GIT 저장소를 이용하여 버전관리를 수행하는 방법으로 전환했습니다. 구성원들은 Markdown 문법을 익혔고 GIT 저장소에 Commit, Push 등의 액션을 수행할 수 있는 구성원은 큰 무리없이 본인이 작성한 내용을 문서에 반영하거나 수정했습니다. 그리고 Bitbucket 의 README 노출 기능을 통해 문서 공유의 역할도 해낼 수 있을 것이라 생각했습니다.

하지만 Bitbucket 의 너드팩토리팀에 가입되어 있는 구성원이 한정적이었고, 프로그램 개발과 전혀 무관한 구성원은 내용을 작성하기 힘들었습니다. 가장 큰 문제점은 문서를 공유하기 힘들었다는 점 입니다. GIT 저장소 관리 Rule 의 공유 부족으로 저장소가 자주 꼬이는 점도 다음 단계로 넘어가는데에 한몫 했습니다.

3. Jekyll Documentation Page

너드팩토리 블로그를 개발하면서 숙달하게 된 Jekyll 이 눈에 띄었습니다. 순수 GIT 저장소를 통해 관리할때 와는 다르게 문서 공유에 효과적이고, Blog Post 작성 방식의 Jekyll 문서관리 시스템은 개별 단위의 문서를 수시로 추가/삭제 하는데에 용이했습니다. Jekyll 은 기본적으로 정적 웹페이지 생성 프레임워크 이기 때문에 문서를 내가 원하는 대로 꾸밀 수 있었습니다.

Make it Real

마지막 단계인 Jekyll 을 사용한 SW 문서 작성 파트에 대한 자세한 소개를 하고자 합니다. 틈 날때마다 구현했지만 총 개발 시간을 따져보면 대략 8시간 정도 소요된것 같습니다.

1. Plan

AIVORY 의 내부 개발자를 위한 문서를 작성했습니다.
전반적인 소개, API 문서, 아키텍처 등의 내용을 구성했습니다.
제품 소개페이지와 같이 메인페이지를 두고 네비게이션을 통해 원하는 문서로 이동하도록 했습니다.
개별적인 API 는 개별적인 document 를 갖도록 했습니다.
API 문서의 경우 메소드 (GET, POST, PUT, DELETE) 를 노출하도록 구성했습니다.

2. Make

Jekyll 의 posts, drafts 기능을 사용하지 않고 별도의 형식을 정해 각 메뉴를 구성했습니다.

_xxxapis -> xxx에 대한 API 문서 단위
_architectures -> 아키텍처를 정의하는 문서 단위
_intro -> 전반적인 소개를 하는 문서 단위

문서별로 별도 yml 양식을 구성했습니다.

---
title: API Development Status
description: APIs 의 개발 현황 입니다.
keywords:
order: 0
comments: false
method: ["GET", "PUT"]

hero:
    title: API Development Status
    text: AI Server APIs 의 개발 현황 입니다.
---

3. Review

Jekyll을 이용해 구현된 개발 문서 웹페이지

Conclusion

能書不擇筆 능서불택일

장인은 도구의 탓을 하지 않는다고 하지만 고집센 점을 잘 잇는 좋은 선(도구)은 효율적인 업무를 위해 꼭 필요하다고 생각합니다. 물론 공유에 용이하다는 것이 주관적인 판단이 앞서는 일이지만 더 좋은 도구를 찾기 위한 노력이 SW를 개발하는 우리를 더 나은 방향으로 이끌어 줄 것이라 믿습니다.