Tesilio

Tesilio

Back-End Developer

개발 문서화 방법 요약본

이 포스팅은 https://lazygyu.net/blog/secrets_of_documentation 이 포스팅을 요약한 글이다.

소개

종류 혹은 역할

  • 튜토리얼
  • 하우-투 가이드
  • 해설 문서
  • 기술 레퍼런스

방법

  • 문서는 위 네 가지의 역할 중 하나에 속해야 하며 그에 맞는 구조를 가져야 한다.
  • 각각의 기능은 완전히 다른 접근 방법으로 작성 되어야 한다.
  • 대부분의 소프트웨어는 네 가지 종류의 문서를 모두 갖출 필요가 있다.

튜토리얼

  • 학습 위주로 이루어져야 한다.
  • 아무것도 모르는 사람이 사용할 수 있게 강좌 형식이어야 한다.

어린 아이에게 요리법을 가르치는 것과 비슷하다.

하우-투 가이드

  • 목표 지향적이어야 한다.
  • 특정한 문제를 해결하는 방법을 보여줘야 한다.
  • 여러 단계로 이루어져 있다.

요리책에 쓰여진 조리법과 비슷하다.

해설 문서

  • 이해를 기반으로 해야 한다.
  • 설명을 해야 한다.
  • 배경 지식과 맥락을 제공해야 한다.

요리의 역사에 대한 기사와 비슷하다.

기술 레퍼런스

  • 정보를 중점으로 해야 한다.
  • 동작을 기술해야 한다.
  • 정확하고 완전한 내용을 담고 있어야 한다.

백과사전 항목을 떠올리면 된다.

프로젝트 문서

  • 변경사항이나 기여 정책 등의 이런 저런 문서는 위 네 종류의 어디에도 속하지 않는다. 소프트웨어 자체에 대한 문서가 아니라 프로젝트 에 관한 문서이기 때문이다.
  • 소프트웨어의 다른 것들과 섞이지 않는 선에서 적당한 곳에 보관하면 된다.

튜토리얼

프로젝트를 달성하는 데까지 독자를 단계적으로 이끌어가는 강좌이다. 학습 지향적인 문서이며, 프로젝트 자체에 대해 배우기보다는 프로젝트를 통해 무언가를 이루는 방법을 배우는 데에 중점을 두어야 한다.

선생님이 되어 학생들을 가르친다고 생각하면 된다. 학생들의 행동과 목표를 결정해야 한다. 제시되는 목표는 의미가 있어야 하며, 완전 초보자(혹은 일정 기준)까지도 달성 가능해야 한다.

튜토리얼을 잘 쓰는 방법

  • 직접 시도해 보며 배우게 해야한다.
  • 어쩄든 시도를 하게 만들어야한다.
  • 반드시 잘 작동해야한다.
  • 결과를 바로 확인할 수 있게 해야한다.
  • 그 어떤 사용자가 시도하더라도 정확히 동작해야 한다.
  • 추상적인 개념보다는 구체적인 단계에 집중해야 한다.
  • 필요한 최소한의 설명만을 제공해야 한다.
  • 사용자가 해야하는 단계에만 집중해야한다.

하우-투 가이드

하우-투 가이드는 현실적 문제를 단계별로 해결하는 방법을 설명한다. 예를 들어 다음과 같다.

  • 웹 폼을 만드는 법
  • 3차원 데이터셋을 도면으로 그리는 법
  • LDAP 인증을 활성화 하는 법

하우-투 가이드는 목표 지향적인 문서이다. 무언가를 먹기 위해 어떤 식재료로 요리하는 방법을 설명하는 조리법(레시피)과 비슷하다.

하우-투 가이드를 잘 쓰는 방법

  • 일련의 단계를 제시해야 한다.
  • 결과물(실용적인 목표)에 집중해야 한다.
  • 문제를 해결해야 한다.
  • 개념을 설명하지 말고 단순히 행동을 나열한다.
  • 같은 일을 하기 위한 여러가지 다른 방법들에 대해 유연한 태도를 가져야 한다.
  • 튜토리얼보다는 실용적으로 힘을 빼도 된다.
  • 적절한 이름을 붙여야 한다.

레퍼런스

레퍼런스는 실제로 작동하는 메커니즘과 그 운용 방식에 대한 기술적인 설명이다. 오직 설명만 하며 정보 지향적이다.

레퍼런스가 설명하는 내용이 클래스나 함수, API, 기타 등등 코드 그 자체이기 때문에 문서의 구조는 코드의 구조를 따르게 된다. 마치 요리법에서 어떤 식재료에 대한 백과사전 항목과 비슷하다.

레퍼런스를 잘 쓰는 방법

  • 문서 구조는 코드에 기반해서 결정해야 한다.
  • 일관적인 표현을 사용해야 한다.
  • 오직 설명만 해야 한다.
  • 정확(최신화)하게 작성해야 한다.

해설 문서

해설 문서는 이해 지향적이다. 해설과 논의로 특정한 주제를 명확히 하거나 주의를 환기시킬 수 있다.

해설 문서를 잘 쓰는 방법

  • 배경과 맥락을 제공한다.
  • 다양한 대안과 의견을 논의한다.
  • 무언가를 지시하거나 기술적 레퍼런스를 제공하지 않는다.

잘 된 예제

  • https://docs.djangoproject.com/en/4.0/
  • https://docs.django-cms.org/en/latest/