#03. 문서화 (Documentation)

Target User

• 소프트웨어 개발과 운영을 좀 더 디테일하게 알고 싶은 분
• 혼자가 아닌 여러 사람이 함께 사용하는 소프트웨어를 개발할 때 어떻게 해야 더 잘할 수 있는지 궁금하신 분
• 한번 배포하고 끝이 아닌, 지속적으로 배포하는 소프트웨어를 개발하시는 분
• 소프트웨어 문서화에 관련된 것들을 알고 싶으신 분

Why you need to know

• 문서화는 혼자 개발하거나 사용자가 나밖에 없는게 아닌 이상, 타인과 소통을 위해 필수적입니다.
• 결국 누군가가 쉽게 이해할 수 있게 문서를 잘 써야하는데, 이 때 최소한 어떤 내용이 들어가야하는지 알아야합니다.
• 스스로 문서를 잘 써두어야, 자신도 나중에 헷갈리지 않고 범위와 우선순위를 명확히 한뒤 개발할 수 있습니다.

Contents

문서화에도 많은 종류가 있지만, 여기서는 가장 중요하다고 생각하는 2가지에 대해서만 다룹니다.

• 개발 전 기술 문서에는 어떤 내용이 들어가야 하는가?
• 개발 후 기술 문서에는 어떤 내용이 들어가야 하는가?

개발 전 기술 문서에는 어떤 내용이 들어가야 하는가?

간단하게 개발을 하는게 아니라면, 개발 전 기술 문서를 잘 작성하는 것은 꽤 중요합니다. 문서를 작성하지 않고, 무작정 코드부터 작성하면 중간에 내가 무엇을 하고있고, 뭘 해야하는지 까먹기 쉽습니다. 특히 혼자 개발하는게 아니라, 팀원과 같이 개발을 해야하고 또 개발할 내용을 누군가에게 공유해야한다면 문서는 필수라고 생각합니다.

개발 전 기술 문서는 크게 다음 2가지가 있습니다.

테크 스펙 문서 (Tech Specification Document)

• 이 개발 프로젝트 사이클을 통해 "무엇" 개발할 것인지를 명확히 합니다.
• 개발 전 프로젝트 사이클의 시작점이 됩니다.
• 주로 다음과 같은 내용이 작성됩니다.
  • 요약
  • 배경
  • 목표
  • 목표가 아닌것
  • 계획
  • 이외 고려 사항들
  • (마일스톤)
• 프로젝트를 진행해나가는 동안 방향을 잡아주는 중심 문서가 됩니다.
• 다음 내용들을 참고해보시면 좋습니다.
  • https://blog.banksalad.com/tech/we-work-by-tech-spec/
  • https://eng.lyft.com/awesome-tech-specs-86eea8e45bb9

시스템 디자인 문서 (System Design Document)

• 개발하고자 하는 무엇을 "어떻게" 구현할 것인지를 명확히 합니다.
  • 개발하고자 하는 전체에 대해서 다룰 수도 있고,
  • 개발하는 핵심 컴포넌트 일부에 대한 문서일 수 있습니다.
• "어떻게"가 명확치 않을 때, 일단 리서치나 개발을 진행한 뒤 개발 이후에 작성하기도 합니다.
• 혹은 너무 개발 내용이 간단한 경우 스킵하기도 합니다.
• 주로 다음과 같은 내용이 작성됩니다.
  • 배경 혹은 문제
  • 요구 사항
  • (특별히 고려해야할 사항)
  • 아키텍처
  • 컴포넌트 작업 흐름
  • (디테일한 구현)
• 다음 내용들을 참고해보시면 좋습니다.
  • https://towardsdatascience.com/ace-the-system-design-interview-uber-lyft-7e4c212734b3

정리하면, 테크 스펙은 개발할 What에 집중하고 독자에 구체적으로 담당자가 아닌 사람 (보통 개발자가 아닌 사람)이 포함이 됩니다.

한편 시스템 디자인 문서는 What의 전체나 일부에 대해 어떻게 개발할지 How에 집중하고, 독자는 보통 담당자나 개발자로 전제합니다. How의 모든 부분을 다 문서화하면 너무 많기 때문에, 핵심이 되는 컴포넌트나 설명이 필요한 부분만 작성하기도 합니다.

개발 이후 기술 문서에는 어떤 내용이 들어가야 하는가?

개발 사이클의 끝에 개발을 완료를 했다면, 다음 사이클의 개발 담당자가 쉽게 개발을 이어나갈 수 있게, 또한 사용자가 쉽게 사용할 수 있게 문서화를 해야합니다. 보통 이런 내용은 쉽게 프로젝트 상단의 README.md 에 작성하며, 경우에 따라서는 별도의 웹 문서에 작성하기도 합니다. 전자의 경우는 보통 작은 팀 내에서 개발하는 경우고, 후자의 경우 외부 사용자가 많은 오픈소스들에서 자주 등장합니다.

개발 이후 문서는 다음과 같이 읽는 독자에 따라 문서에는 다음과 같은 내용이 담기곤 합니다.

공통 사항

• 이 소프트웨어가 하는 일과 목적
• 설치나 사용전 사전 요구사항 (OS, 기반 소프트웨어 버전 등)
• 이슈나 개발자와 소통할 수 있는 방법 (이메일, 슬랙 등)

소프트웨어 사용자 대상으로하는 문서

• 소프트웨어를 어떻게 설치하고 어떻게 사용하는지에 대한 내용
  • Getting Started 혹은 Quick Start에 대한 내용
  • 전체적인 Architecture 에 대한 내용
  • Detail 한 사용 방법
• 테크 스펙 문서에 들어가는 내용들

소프트웨어 개발자를 대상으로 하는 문서

• 이 소프트웨어의 개발 환경 셋업하는 방법
• 프로젝트 구조 및 각 패키지별 역할
• 개발 중 테스트 하는 방법
• 이 소프트웨어에 기여하는 방법
  • PR, Commit, Branch 규칙
• 시스템 디자인 문서에 들어가는 내용들

보통 위와 같은 내용은 합쳐져서 다음처럼 README.md 에 담기는게 일반적이긴 합니다.

• https://github.com/zzsza/Boostcamp-AI-Tech-Product-Serving
  • 이 Repo 역시 위 두 독자를 모두 고려하여 README.md 가 작성되었습니다.
• https://github.com/AliyunContainerService/gpushare-scheduler-extender
  • 제가 최근에 본 README.md 중 심플하지만 꽤 잘 작성되었다고 느낀 문서입니다.
  • 특히 Design Document를 통해 System Design이 어떻게 되었는지 쉽게 파악할 수 있었습니다.

개발한 소프트웨어에 대해 별도의 웹 문서를 기록하는 경우는 오픈소스에서 흔하게 볼 수 있습니다. 보통 프로젝트 상단에 docs/ 디렉토리 내에 담으며 mkdocs, vuepress 등의 툴로 배포하곤 합니다. 아래 오픈소스들이 대표적인 예시입니다.

• https://github.com/apache/airflow
• https://github.com/mlflow/mlflow
• https://github.com/dagster-io/dagster

Alternatives

문서화에 주로 다음과 같은 도구들을 간단히 소개해봅니다.

• mermaid.js
  • 여러 다이어그램을 as a code로 작성할 때 많이 씁니다.
  • Github README.md 도 mermaid.js 로 작성된 코드를 렌더링해줍니다.
• diagrams
  • 클라우드를 사용하는 경우 code로 클라우드 리소스간의 diagram을 그릴 수 있습니다.
• draw.io
  • 일반적으로 다이어그램 그릴 때 가장 많이 사용하는 툴입니다.
• mkdocs-material
  • 문서를 쉽고 빠르고 이쁘게 렌더링 해줍니다.
    • https://fastapi.tiangolo.com/ 이런 UI를 가진 문서를 작성할 수 있습니다.
  • 많은 오픈소스들이 이 툴을 기반으로 사용자 문서를 작성하곤 합니다.
• vuepress
  • mkdocs와 마찬가지로 문서를 쉽고 빠르고 이쁘게 렌더링 해줍니다. 다만 vue 기반입니다.

그 외 다양한 도구에 대해서는 아래 문서를 참고헤보세요!

• https://github.com/testthedocs/awesome-docs