문서화란

문서화란 개발자들이 작성하는 소프트웨어에 대해 기술하는 것을 의미한다. 문서화 능력은 개발자로서 매우 중요한 덕목이며 습관이 되어야 하는 부분이다

문서화는 크게 4가지 종류로 나눌 수 있는데

• 튜토리얼(Tutorial)
• 하우-투 가이드(How-to guide)
• 해설(Explanation)
• 기술 레퍼런스(Technical reference)
  등의 네 가지 역할 중 하나에 속하도록 목적을 정하여 작성해야 한다

그리고 각각의 문서는 목적이 다르기 때문에 서로 다른 접은 방식으로 작성되어야 한다

목적에 따라 나뉘어야 하는 이유

이러한 구분은 작성자와 독자 양측에게 방향성을 제시해준다. 작성자에겐 어떤 주제에 관하여 어떤 목적을 가지고 어디에, 어떤 방식으로 기술해야할 지 지침이 되며 독자는 어떠한 목적을 이루기 위해 이 글을 읽는지 알고있기 때문에 이해하기 좀 더 수월해진다

또한 이러한 분류체계는 힘이 한 점으로 모이게 해준다. 분류 체계가 명시되지 않는다면 물체를 미는 행위를 할 때 어느 한쪽으로 밀어야 할지 모르고, 사방팔방 떠돌다가 기력만을 소진한 채 아무런 목적도 이루지 못하게 될 것이다

프로젝트 문서

프로젝트 문서는 소프트웨어에 대한 문서가 아니라 소프트웨어를 만들기 위한 프로젝트에 관한 문서이기 때문에 어떠한 경우에도 속하지 않는다

프로젝트 문서는 프로젝트 문서로서 관리하면 되며, 적당한 곳에 적당히 보관하면 된다

튜토리얼(Tutorial)

튜토리얼은 학습 위주로 되어있고, 아무런 기반지식이 없는 사람이 제품을 사용할 수 있도록 도와주는 강좌이다

소프트웨어를 사용하여 어떠한 목적을 달성하는 데까지 독자를 단계적으로 이끌어가는 강좌이며, 이를 통해 목적을 달성하는 방법과 순서를 유저에게 보여줄 수 있다

이는 학습 지향적인 문서를 뜻하게 되는 것이며 소프트웨어 자체에 대해 학습하기 보다 소프트웨어를 사용하여 무언가를 이루는 방법에 중점을 두고 있다

당신은 교육자가 되어 책임을 가지고 학습자들에게 가르쳐야 하는 입장이다. 당신의 설명에 따라 학습자들은 어떠한 목표를 이루기 위해 행동을 실행하게 될 것이다

학습자들의 목표와 달성하기 위한 행동의 흐름은 당신이 결정해야 한다. 목표는 의미가 있어야 하며 처음 사용해보는 초보자도 달성할 수 있을 정도로 쉬어야 한다

예를 들어 아이에게 요리를 가르친다고 가정하면, 어떤 요리인지는 크게 중요하지 않다. 진짜 중요한 것은 요리의 즐거움을 깨닫게 해 주는 것이며 다른 요리에 도전하고 싶은 마음을 심어주는 것이다. 과정을 통하여 요리에서 중요한 것은 무엇인지, 요리를 하는 것은 어떤 느낌인지, 도구는 어떻게 사용하는지, 음식은 어떻게 다루어야 하는지를 배우는 것처럼 말이다

우리는 소프트웨어를 사용할 때 우선 직접 실행시켜 본다다. 이처럼 요리와 소프트웨어에는 같은 점이 있는데 이론적인 지식이긴 하지만 결국 직접 해보며 익혀야 하는 점이다. 여기에서 튜토리얼의 목적이 있다. 튜토리얼은 요리와 소프트웨어가 그러듯 학습자를 사용자로 탈바꿈 시켜주어야 하는데 튜토리얼의 수준이 낮거나 없다는 사실은 새로운 사용자가 소프트웨어에 유입되는 것을 가로막는 장벽으로서 기능할 것이다

좋은 튜토리얼을 작성하는 것이 어려운 이유는 이러한 이유와 같이 초보자에게도 유용해야 하며 따라가기에도 쉬어야 하고, 그 시간이 의미가 있어야 하기 때문이다

튜토리얼을 잘 쓰는 방법

우리는 결국 이론적인 지식을 경험으로서 체화시켜야 한다. 때문에 튜토리얼을 진행하며 사용하가 직접 시도해보면서 배우게 해야한다. 뭐든 처음에는 직접 해보면서 배우며, 아기들이 걷는 것을 처음에는 못하지만 점차 잘하게 되는 것처럼 소프트웨어도 마찬가지다. 처음에는 단순하게 시작하며 점진적으로 자연스러워 지고 복잡한 것들을 다룰 수 있게 해야한다

튜토리얼의 중요한 점은 학습자가 여정을 시작하게 하는 데에 있는 것이지, 목적지에 데려다 주는 데에 있는 것이 아니다. 보호자는 아기가 걸을 수 있게 도와주는 것이지 다음 뛰는 행위는 결국 점차 깨닫게 것처럼 말이다

또한 학습자의 자신감을 복돋아주는 역할이 중요하다. 튜토리얼이 제시하는 과제를 달성할 수 있다는 자신감을 불어넣을 수 있어야 한다. 그리고 제시한 과제는 반드시 제대로 동작해야 한다
학습자의 행동이 이상한 결과나 오류를 만들어낸다면 그 튜토리얼문서는 잘못된 것이다. 학습자는 시킨대로 행동을 했을 때 반드시 효과를 확인할 수 있어야 한다

학습자가 하는 모든 행동은 아무리 사소하더라도 이해할 수 있는 뭔가를 달성해야 한다. 본인의 행동으로 이루어진 과정과 결과물을 이해할 수 없다면 시간도 낭비될 뿐더러 흥미를 잃게된다

만약 과정만 이해 된다면, 튜토리얼은 반복이 가능하기 때문에 숙련될 수 있는 여지가 있다. 이는 반대로 말하면 튜토리얼은 반드시 반복이 가능해야 한다. 사람끼리의 첫인상이 중요한 것처럼 사람들은 튜토리얼을 사용하여 그 소프트웨어를 처음 접해보는 것이다. 때문에 그 어떤 유저가 시도하더라도 항상 정확히 동작해야 하며 정확하게 반복이 가능해야 한다

추상적인 개념보다는 구체적인 단계에 집중하기

튜토리얼은 정확한 행동과 결과를 바탕으로 구체적인 내용을 담고 있어야 한다

추상화야말로 컴퓨터 공학의 힘의 원천이기 때문에 추상적인 내용을 소개하고 싶은 유혹은 아주 강렬할 것이다. 하지만 걷지도 못하는데 뛸 수 없는 것처럼 모든 학습의 과정은 단계를 밟아 구체적으로 진행되어야 한다

학습자가 구체적인 내용에 대해 충분히 곱씹어볼 기회를 갖기도 전에 다음 단계로 나아가는 것은 잘못된 교습 방법이다

필요한 최소한의 설명만을 제공하기

굳이 지금 필요하지 않은 지식을 모조리 설명할 필요가 없다. 생각의 스펙트럼을 넓히는 일은 인간으로서 대단히 중요하지만 그 일을 지금 할 필요는 없다. 직접 설명을 하는 대신 다른 설명이 나와있는 문서를 링크로 제공하는 등, 우회적인 방법이 많다

튜토리얼은 당장 해야 하는 작업에만 집중할 필요가 있다. 당신이 방금 소개한 명령어가 정말 많은 일을 할 수 있고 많은 옵션을 가지고 있을 수 있지만, 그러한 옵션은 목적을 달성하는데 필요한 요소가 아니다

하우-투 가이드(How-to guide)

가이드는 어떠한 목표를 달성하기 위해 목표 지향적으로 서술되어야 하며 이슈를 해결하는 방법을 보여주여야 하고, 단계적으로 구성되어야 한다

예를 들어 '객체를 만드는 법', '상수를 선언하는 법', 'Console.WriteLine() 명령어를 사용하는 법'과 같이 특정한 목표를 달성하기 위한 안내서이다

비유하자면, 음식을 먹는다는 목표을 달성하기 위하여, 음식 중 하나인 라면을 끓이는 방법을 설명하는 것과 같다

이 문서는 어떠한 목표를 달성하기 위한 과정을 설명하는 것이며, 이 문서를 읽는 사람이 이미 기본적인 지식을 갖추었을 것이라 전제할 수 있다. 하우-투 가이드는 튜토리얼과는 완전히 다르다. 하우-투 가이드는 튜토리얼이 대상으로 할 만한 진짜 초보자로서는 떠올리지도 못할 질문에 대한 해답을 제시한다

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

절차적으로 작성하는 것이 중요하다. 한마디로, 일련의 단계를 제시하라

하우-투 가이드는 순서대로 따라야 하는 단계별 목록을 제시하는데 아주 초보적인 부분 부분은 건너뛰고 적당하다고 시작되는 부분을 시작점으로 선택할 수 있다. 때문에 튜토리얼처럼 반드시 반복 가능한 견고한 구조까지는 필요하지 않다

이 문서는 실용적인 목표에 집중해야한다. 그 외에 다른 것은 부차적인 문제이며 과도한 설명은 지양해야 한다

또한 반드시 특정한 문제나 질문에 대한 해답을 제시해야 한다. 라면을 끓이는 방법이기 때문에 그에 따라 파생할 수 있는 다른 이슈에 대한 해답이 있어야 한다

이 점이 하우-투 가이드가 튜토리얼과 차별화되는 부분이다. 이 문서를 읽는 독자는 자신의 목적이 무엇인지는 짐작하고 있지만 구체적인 방법은 모를 뿐이기 때문에 튜토리얼에서 필자가 흐름을 결정하듯, 독자가 이슈를 해결하기 위해 무엇을 알아야 할지 선별할 책임이 있다

실용적이여야 한다

이 문서에서는 뭔가를 설명하지 않는다. 그런 종류의 논의를 하기 위한 무대가 아니며 단순히 행동을 나열하면 된다. 중요한 설명이 필요하다면 해당 설명에 대한 링크를 제공하라

그리고 이러한 점은, 바로 목적을 달성하기 위한 길을 제시하는 것 뿐이기 때문에 유연성을 허용해야 한다. 같은 목적을 달성하기 위한 여러가지 다른 방법들에 대해 유연한 태도를 가져야 한다. 너무 특정한 상황에서만 들어맞는 문서는 정확히 동일한 상황이 아니라면 쓸모가 없을 것이다

완벽한 것 보다는 실용성에 중점을 두어야 한다. 튜토리얼은 완성도가 높고 처음부터 끝까지 제대로 설명해야 하지만 하우-투 가이드는 그럴 필요가 없다. 내용이 너무 빵빵한 문서는 유저에게 빠른 해결책을 제공할 수 없다. 때문에 문서가 무엇을 설명하고 있는 지를 정확하게 드러내는 제목을 붙일 필요성이 있다

해설(Explanation)

해설 문서는 이해를 시켜주는 목적을 가졌으며 때문에 배경 지식과 맥락을 제공하며 그러한 정보들을 바탕으로 설명을 해야한다. 정리하자면 이해 지향적이다

해설 문서는 논의 문서라고도 한다. 이 문서들은 소프트웨어 자체에서 한 발짝 물러나서 더 넓은 시야, 혹은 기존과 다른 관점에서 소프트웨어를 바라볼 수 있게 해준다

해설 문서는 배경과 맥락을 제공하는 곳이다. 예를 들어 'C# 언어의 특성', '캐시 메모리의 동작 원리' 등의 주제를 말한다. 한 문서에 담기 적당하다고 생각하는 내용들이 바로 해설/논의 문서이다

이 문서에서는 여러 대안들이나 다각도의 접근을 고려할 수 있다. 또한 서로 반대되는 의견들을 저울대에 올릴 수도 있다

해설 문서는 다른 문서들이 제공하지 않는 내용을 제공해야 한다. 이 문서는 사용자에게 무언가를 사용하는 방법을 지시하거나 설명하는 곳이 아니기 때문이다

레퍼런스(Reference)

레퍼런스는 정보를 중점으로 어떻게 동작하는지 포커스를 맞추어 기술하며 정확하고 완전한 내용을 담아야 한다. 비유하자면, 백과사전의 항목과 같다

레퍼런스는 오직 설명만 한다. 때문에 정보 지향적이다. 그리고 간결하고 정중해야 한다

이 문서에서는 기능을 어떻게 사용하는지에 관한 기초적 설명이 꼭 포함되어 있어야 하며 이러한 점이 레퍼런스와 하우-투 가이드를 구분짓는 차이점이다. 소프트웨어의 정확한 사용법을 설명하는 것(레퍼런스)은 특정한 목적을 달성하기 위한 방법을 보여주는 것(하우-투 가이드)과는 전혀 다르다

레퍼런스를 잘 쓰는 방법

문서 구조는 코드에 기반해서 결정하라

레퍼런스 문서의 구조를 코드 베이스와 동일하게 만들면 사용자는 코드와 레퍼런스 문서를 함께 참조할 수 있다. 또한 이렇게 하면 관리자들도 쉽게 문서화 과정에서 빠진 부분이나 갱신이 필요한 부분을 발견할 수 있다

레퍼런스 문서는 다른 사전들 처럼 구조, 어조, 형식등을 항상 일관성 있게 사용해야 한다. 그리고 오직 설명만 하라. 레퍼런스 문서에 요구되는 유일한 기능은 바로 명확하고 완전한 설명이다. 그외 해설·논의·조언·추측·의견 등은 문서를 활용하기도 유지보수하기도 어렵게 만든다. 필요하다면 설명을 위한 적절한 예제를 제공하라

레퍼런스 메뉴얼에 기본적인 소프트웨어 사용법을 넘어 특정한 목적을 이루기 위한 응용법을 설명하고 싶은 유혹을 떨쳐내라. 개념을 설명하고 싶은 욕심이나 개발과 관련된 사항을 논의하고 싶은 충동도 이겨내야 한다

정리

튜토리얼과 하우-투 문서는 실용적인 단계를 설명한다는 점에서 비슷하고, 하우-투 가이드와 레퍼런스는 실제로 코딩하거나 일하면서 필요하다는 점에서 비슷하다. 또한 레퍼런스와 해설은 이론적인 지식을 다룬다는 점에서 비슷하다. 게다가 튜토리얼과 해설 문제는 작업을 할 때 보다는 공부를 할 때 더 유용하다는 점이 비슷하다

이렇게, 각자의 영역들이 조금씩 겹치기 때문에 구분이 혼란스럽고 섞여버린다

문서 작업자들의 가장 큰 두통거리 중 하나는 그들이 해야 하는 일이 뭔지 정확히 예측할 수가 없다는 것이다. 하지만 이 글에서 정리한 구조로 명확한 분류를 통해 지향점을 잡아준다. 이러한 방식은 문서를 작성하고 유지보수가 용이하게 만들어 준다

---

Reference

이 글은 다음의 글을 보고 작성하였습니다
문서화에 대해 아무도 말해주지 않는 것들