문서화에 대해 아무도 말해주지 않는 것들

역주 : 이 글은 What nobody tells you about documentation 을 번역한 글입니다. 오타 및 오역 지적 환영합니다.

아무리 문서 작업에 노오력을 쏟아봤자 방향을 잘못 잡으면 소프트웨어의 품질에는 전혀 도움이 되지 않습니다.

좋은 문서 작업을 위해서는 반드시 알아두어야 할 비결이 있습니다. 바로 문서를 단순히 그냥 '문서’로 퉁치는 인식이 바르지 않다는 겁니다. 문서에는 네 가지 종류가 있습니다.

튜토리얼, 하우-투 가이드, 해설, 기술 레퍼런스가 바로 그 네 가지입니다. 이 네 가지는 각기 다른 목적이나 기능을 가지고 있고 각각의 작성을 위해서 서로 다른 접근법이 요구됩니다. 이것들이 뭘 의미하는지를 이해하는 것은 문서화의 질을 향상시키는 데에 큰 도움이 됩니다.

서론

문서화가 똑바로 되어있지 않으면 소프트웨어가 아무리 잘 만들어져 있더라도 사람들은 사용하지 않습니다.

행여 다른 선택지가 없어서 강제로 그 소프트웨어를 써야 하는 상황이라 해도 제대로 된 문서가 없으면 유저들은 소프트웨어를 당신의 의도와는 전혀 다르거나 비효율적인 방법으로 사용하게 될 것입니다.

대다수의 사람들은 유저에게 좋은 문서가 필요하다는 것을 알고 있고, 좋은 문서를 만들기 위해 노력합니다.

그리고 대부분 실패합니다.

노력이 부족해서 실패하는 경우는 별로 없습니다. 그보다는 노력을 했으나 그 노력의 방향이 잘못되었기 때문에 망하는 경우가 일반적이죠.

이 포스팅을 통해서 필자는 어떻게 하면 문서화를 더 잘 할 수 있는지를 설명하고자 합니다. 무작정 노오력을 하는 것 보다는 제대로 된 방향을 잡을 수 있게요. 올바른 방법은 사실 더 쉬운 방법이기도 합니다. 작성하기에도 더 쉽고 관리도 더 용이하죠.

잘 언급되지는 않지만 문서화를 지배하는 몇 가지 단순한 원칙이 존재합니다. 별로 비밀도 아닌데도 자주 비밀스럽게 묻혀있는 것들이죠.

이 원칙들에 숙달 되기만 한다면 당신의 문서와 프로젝트는 한결 나아질 것입니다. 더 나아가서 당신의 제품과 당신의 팀도 발전하게 될 겁니다. 두고 보세요.

비결

문서화는 튜토리얼Tutorial/하우-투 가이드How-to guide/해설Explanation/기술 레퍼런스Technical reference 등 네 가지의 역할 중 하나에 속해야 하며 거기에 알맞는 구조를 가져야 합니다. 각각의 기능은 서로 완전히 다른 접근 방법으로 작성 되어야 합니다. 유저들은 서로 다른 상황과 서로 다른 시점에 이들 문서를 찾게 되기 때문에 대부분의 소프트웨어는 저 네 가지 종류의 문서를 모두 갖출 필요가 있습니다.

문서는 명시적으로 이들 중 한 가지의 구조를 가져야 하고, 다른 종류의 문서들과 명확하게 구분되어야 합니다.

튜토리얼

튜토리얼은

• 학습 위주로 이루어져 있고
• 뉴비가 제품 사용을 시작할 수 있도록 해주는
• 강좌입니다.

비유하자면, 어린 아이에게 요리법을 가르치는 것과 비슷합니다.

하우-투 가이드

하우-투 가이드는

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

요리책에 쓰여진 조리법을 떠올려보세요.

해설 문서

해설 문서는

• 이해를 기반으로 하며
• 설명하고
• 배경 지식과 맥락을 제공합니다.

요리의 역사에 대한 기사를 생각해보세요.

레퍼런스

레퍼런스는

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

백과사전 항목을 떠올려 보시면 됩니다.

이러한 구분은 작성자와 독자 양측에게 정보의 향방에 대한 분명한 예측을 가능하게 합니다. 작성자 입장에서는 무엇을, 어디에, 어떻게 써야 하는지에 대한 지침이 됩니다. 그럴싸한 문서를 만들어내기 위해 수많은 정보들과 씨름하는 고통에서 작성자를 구해주는 것이죠. 각 종류의 문서는 각각 단 하나의 목적만을 가지고 있으니까요.

사실, 명시적으로든 암시적으로든 이 네 가지 중 하나로 분류되지 않는 문서는 관리하기 어렵습니다. 각각의 문서는 다른 문서들과 완전히 다른 요구사항을 가지고 있기 때문에, 이러한 분류 체계를 유지하지 못하는 문서를 관리하는 것은 마치 한 번에 사방팔방으로 줄을 모두 당기려는 것과 같습니다.

일단 이 분류 체계를 이해하게 되면, 이미 존재하는 문서들을 분석하고 어떻게 그 문서들을 향상시킬 수 있는지 이해하는 데에도 아주 유용한 지식이 될 것입니다.

프로젝트 문서

변경사항change logs이나 기여 정책contribution policy이나 기타 프로젝트에 관련된 이런 저런 문서들은 어떤 분류에 해당하는지 아마 의문이 들텐데요, 정답은 저 문서들이 그 중 어디에도 해당하지 않는다는 것입니다. 엄밀히 말해서 저 문서들은 ‘소프트웨어’ 자체에 대한 문서가 아니라 프로젝트에 관한 문서들이기 때문입니다.

저것들은 그냥 소프트웨어의 다른 것들과 섞이지 않는 선에서 적당한 곳에 적당히 보관하면 됩니다.

프로젝트 문서에 관한 위 사항을 기억해두고 이제부터 네 가지 문서 종류 각각에 대해 살펴보도록 하겠습니다.

튜토리얼

튜토리얼은 어떤 프로젝트를 달성하는 데까지 독자를 단계적으로 이끌어가는 강좌입니다. 이를 통해 이 프로젝트로 무언가를 달성하는 방법과 순서를 초보자에게 보여줄 수 있습니다.

이는 전체적으로 학습 지향적인 문서이며, 특히 프로젝트 자체에 대해 배우기보다는, 프로젝트를 통해 무언가를 이루는 방법을 배우는 데에 중점을 두고 있습니다.

당신은 선생님이 되어, 책임을 가지고 학생들을 가르쳐야 합니다. 당신의 설명을 따라서 학생들은 어떤 목표를 이루기 위한 일련의 행동을 실행하게 됩니다.

학생들의 행동과 목표는 당신이 결정해야 합니다. 하지만 목표를 결정하는 것은 쉬운 일이 아닙니다. 제시되는 목표는 충분히 의미있으면서도, 완전 초보자까지도 달성할 수 있음직한 것이어야 합니다.

아이에게 요리를 가르친다고 가정해 봅시다

어떤 요리를 가르칠 것인지는 사실은 별로 중요한 게 아닙니다. 진짜 중요한 것은 아이가 요리의 즐거움을 깨닫고 자신감을 갖게 되는 것, 더욱 도전하고 싶은 마음을 심어주는 것입니다.
요리하는 과정을 통해서 아이는 요리에서 중요한 것들이 무엇인지 배우게 됩니다. 주방에 있는 게 어떤 느낌인지, 식기들을 어떻게 사용하는지, 음식을 어떻게 다뤄야 하는지를 배우는 것이죠.

소프트웨어를 사용하는 것은 요리를 하는 것처럼 기능적인 작업입니다. 지식이긴 하지만 이론적인 지식이라기보다는 실제로 겪어봐야 하는 종류의 지식이죠. 우리는 이런 류의 새로운 기술이나 재주를 처음 배울 땐 늘 우선 직접 해보는 데서 시작하곤 합니다.

중요한 점은, 튜토리얼을 모두 완료한 학습자가 나머지 다른 문서들과 해당 소프트웨어 자체를 이해할 수 있는 위치에 선다는 것입니다.

대부분의 소프트웨어 프로젝트는 튜토리얼이 아예 없거나 있더라도 아주 구질구질합니다. 튜토리얼이란 건 '학습자’를 '사용자’로 탈바꿈시켜주는 문서입니다. 튜토리얼이 후지거나 아예 없다는 건, 새로운 사용자가 프로젝트에 유입되는 것을 가로막는 장벽이 됩니다.

좋은 튜토리얼을 작성하는 것은 아주 어렵습니다. 초보자에게도 유용해야 하고, 따라가기에도 쉬워야 하며, 의미있게 잘 짜여져있어야 하니까요.

튜토리얼을 잘 쓰는 방법

직접 시도해 보면서 배우게 하세요

우리는 뭐든 처음에는 직접 해보면서 배웁니다. 옹알이나 걸음마처럼요.

소프트웨어 튜토리얼에서 학습자는 무언가를 직접 실행해야 합니다. 튜토리얼에서 요구하는 행동들은 가능한 여러가지 도구와 조작을 접하도록 해주는 것이 좋습니다. 처음에는 단순한 것을 만들고 점진적으로 복잡한 것들을 다루게 해야 하고요.

일단은 어쨌든 시도를 하게 만드세요

초보자의 첫 걸음은 손을 잡고 이끌어주는 걸음마여도 충분합니다. 마찬가지로 초보자에게 처음 알려주는 방법이 ‘경험자라면 절대 하지 않을’ 방법이거나 ‘올바르지 않은’ 방법이어도 괜찮습니다. 튜토리얼은 모범 사례 설명서가 아니니까요.

튜토리얼의 중요한 점은 학습자가 여정을 시작하게 하는 데에 있는 것이지 그들을 목적지에 데려다 주는 데에 있는 것이 아닙니다.

튜토리얼은 반드시 잘 작동해야 합니다.

선생님으로서 해야 할 일 중 하나는 초보자의 자신감을 복돋아주는 것입니다. 소프트웨어, 튜토리얼, 학습 과정 자체에 대한 자신감도 그렇고, 튜토리얼이 제시하는 과제를 달성할 수 있다는 자신감까지 불어넣어 주어야 합니다.

친근한 조언, 일관성 있는 언어 사용, 자료들을 통한 논리적 진행 등 자신감을 복돋아주기 위한 많은 방법들이 있습니다. 하지만 이런 방법들보다 우선 가장 중요한 점은 제시한 과제가 반드시 제대로 동작해야 한다는 것입니다. 학습자는 당신이 시킨대로 어떤 행동을 했을 때 반드시 당신이 말 한대로의 효과를 확인할 수 있어야 합니다.

학습자의 행동이 이상한 결과나 오류를 만들어낸다면 튜토리얼은 망한 것입니다. 당신 탓이건 아니건 그런건 중요하지 않습니다. 옆에서 학생을 보고 있다면 그 자리에서 어떻게든 해결해 줄 수 있겠지만 학생이 그저 혼자서 튜토리얼 문서를 읽고 있는 거라면 그럴 수가 없습니다. 따라서 그런 일이 일어나지 않도록 미리 미리 대비를 해야 합니다. 물론 말처럼 쉬운 건 아닙니다만.

유저가 결과를 바로 확인할 수 있도록 하세요.

학습자가 하는 모든 행동은 아무리 사소하더라도 이해할 수 있는 뭔가를 달성하는 것이어야 합니다. 혹시 학생이 이해가 안 가는 뻘짓을 두 페이지씩 따라 해야 겨우 결과를 확인할 수 있다면 그건 좀 너무한거죠. 모든 행동의 효과는 가능한 빠르고 분명하게 눈에 보여야 합니다. 물론 행동과 결과의 연관성도 명확하게 드러나야 하구요.

또한, 튜토리얼의 각 섹션의 결론, 튜토리얼 전체를 아우르는 결론은 반드시 의미있는 성과여야 합니다.

튜토리얼을 반복할 수 있게 만드세요.

튜토리얼은 반드시 반복이 가능해야 합니다. 그렇게 만드는 게 쉽진 않지만요. 사람들은 튜토리얼에 여러가지 운영체제와 도구를 통해서 찾아오고, 각 개인이 가진 경험도 천차만별입니다. 게다가 같은 유저라고 하더라도 사용하는 프로그램이나 자원들은 매번 조금씩 달라져있을 가능성이 큽니다.

그 어떤 유저가 시도하더라도 튜토리얼은 항상 정확히 동작해야 합니다.

안타깝지만 튜토리얼이 그렇게 잘 작동하는 것을 확인하기 위해서는 정기적이고 세심한 테스트가 필요하겠죠.

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

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

추상적인 내용을 소개하고 싶은 유혹은 아주 강렬합니다. 추상화야말로 대부분의 컴퓨터 공학의 힘의 원천이니까요. 하지만 모든 학습의 과정은 구체적이고 특정한 부분으로부터 점차 일반적이고 추상적인 방향으로 진행되어야 합니다. 학습자가 구체적인 내용에 대해 충분히 곱씹어볼 기회를 갖기도 전에 추상화의 이점을 설파하려 드는 것은 잘못된 교습 방법입니다.

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

굳이 학습자에게 별로 필요도 없는 지식을 모조리 설명하려 들지 마세요. 물론 논의의 지평을 넓히는 것은 중요한 일이지만, 굳이 튜토리얼에서 그럴 필요는 없습니다. 그런 내용들은 그냥 학습의 방해물에 불과합니다. 필요 최소한의 설명이 딱 적당합니다. 튜토리얼에서 직접 설명을 하는 대신 어디 다른 문서에 있는 설명을 링크로 제공하세요.

오직 사용자가 해야 하는 단계에만 집중하세요.

튜토리얼은 당장 해야 하는 작업에만 집중할 필요가 있습니다. 당신이 방금 소개한 명령어가 다른 수많은 옵션을 가지고 있을 수도 있겠죠. 혹은 어떤 API 에 접근하는 수많은 다른 방법들이 있을 수도 있구요. 하지만 그딴 게 무슨 상관이 있겠습니까. 지금 당장 튜토리얼을 진행하는 데 필요한 것도 아닌데.

하우-투 가이드

하우-투 가이드는 현실적 문제를 단계별로 해결하는 방법을 설명합니다.

하우-투 가이드는 특정한 목표를 달성하기 위한 안내서입니다. 예를 들어 ‘웹 폼을 만드는 법’, ‘3차원 데이터셋을 도면으로 그리는 법’, ‘LDAP 인증을 활성화 하는 법’ 같은 것들이죠.

하우-투 가이드는 목표 지향적인 문서입니다.

비유하자면, 무언가를 먹기 위해서 어떤 식재료를 요리하는 방법을 설명하는 조리법과 비슷합니다.

조리법은 명확하게 정의된 목표가 있고 특정한 질문을 다룹니다. 이 문서는 어떠한 목표를 달성하기 위한 과정을 설명하는 것이며, 이 문서를 읽는 사람이 이미 기본적인 지식을 갖추었을 거라고 전제할 수 있습니다.

하우-투 가이드는 튜토리얼과는 완전히 다릅니다. 하우-투 가이드는 튜토리얼이 대상으로 할 만한 진짜 초보자로서는 떠올리지도 못 할 만한 질문에 대한 해답을 제시합니다.

하우-투 가이드에서는 독자가 어느 정도의 기본적 지식과 이해를 가지고 있다거나, 이미 기본적인 방법과 도구 활용법을 알고 있다고 가정하고 설명할 수 있죠.

하우-투 가이드 문서는 대체로 꽤 잘 갖춰져있는 경우가 많습니다. 작성하기에도 쉽고 재밌는 편이죠.

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

일련의 단계를 제시하세요

하우-투 가이드는 순서대로 따라야 하는 단계별 목록을 제시합니다(튜토리얼과 흡사합니다). 굳이 아주 초보적인 부분보다는 적당하다고 생각되는 부분을 시작점으로 선택할 수 있습니다. 하우-투 가이드는 신뢰할 수 있어야 하지만 튜토리얼처럼 반드시 반복 가능해야 하는 견고한 구조까지는 필요하지 않습니다.

결과물에 집중하세요

하우-투 가이드는 실용적인 목표에 집중해야 합니다. 그 외의 다른 것은 모두 부차적인 문제입니다. 튜토리얼에서와 마찬가지로, 과도한 설명은 지양해야 합니다.

문제를 해결하세요

하우-투 가이드는 반드시 특정한 문제나 질문에 대한 해답을 제시해야 합니다. 이 문서는 “ㅇㅇㅇ을 하는 방법” 이니까요.

이 점이 바로 하우-투 가이드가 튜토리얼과 차별화되는 부분입니다. 하우-투 가이드를 읽는 독자는 자신이 하고자 하는 게 무엇인지는 이미 짐작하고 있습니다. 다만 구체적인 방법을 모를 뿐이죠. 튜토리얼에서처럼 당신은 독자가 해당 문제를 해결하기 위해 무엇을 알아야 하는지를 결정할 책임이 있습니다.

개념을 설명하지 마세요

하우-투 가이드는 뭔가를 설명하지 않습니다. 그런 종류의 논의를 하기 위한 무대가 아닙니다. 하우-투 가이드에서는 단순히 행동을 나열하면 됩니다. 만약 중요한 설명이 필요하다면 해당 설명에 대한 링크를 제공하세요.

어느정도의 유연성을 허용하세요

하우-투 가이드는 같은 일을 하기 위한 여러가지 다른 방법들에 대해 유연한 태도를 가져야 합니다. 여러 비슷한 경우들에 대해 제시된 내용이 어떻게 적용이 가능한지 유저가 알 수 있을 정도, 혹은 비슷한 다른 시스템이나 환경에서 어떻게 이 방법을 적용할 있는지 알 수 있을 정도면 충분합니다. 너무 특정한 상황에서만 들어맞는 문서는 정확히 동일한 상황이 아니면 쓸모가 없겠죠.

내버려 두세요

완벽한 것 보다는 실용적인 것이 중요합니다. 튜토리얼은 완성도가 높고 처음부터 끝까지를 제대로 설명해야 하지만 하우-투 가이드는 그럴 필요가 없습니다. 하우-투 가이드는 시작와 끝을 적당히 정해도 됩니다. 주제와 관계된 것이 있다고 해서 굳이 그 것들을 모조리 언급할 필요도 없습니다. 내용이 너무 빵빵한 하우-투 가이드는 유저에게 빠른 해결책을 제공하지 못합니다.

적절한 이름을 붙이세요

하우-투 가이드의 제목은 이 문서가 무엇을 설명하고 있는지를 정확하게 드러내야 합니다. ‘클래스 기반 뷰를 만드는 방법’ 은 좋은 제목입니다. '클래스 기반 뷰 만들기’는 좀 애매하네요. '클래스 기반 뷰’라는 제목은 영 별로입니다.

레퍼런스

기술 레퍼런스는 실제로 작동하는 메커니즘과 그 운용 방식에 대한 기술적인 설명입니다.

레퍼런스는 오직 설명만 합니다. 레퍼런스가 설명하는 내용이 클래스나 함수, API, 기타 등등 코드 그 자체이기 때문에 문서의 구조는 코드의 구조를 따르게 됩니다. 또한 레퍼런스는 함수, 멤버 변수, 속성, 메소드 같은 것들의 목록을 나열하고 그것들을 사용하는 방법을 제시합니다.

레퍼런스는 정보 지향적입니다.

기술 레퍼런스는 사용법을 묘사하기 위한 예제를 포함할 수도 있지만 기본적인 개념을 설명하거나 공통적인 작업을 달성하는 방법을 설명하기 위한 예제여서는 안됩니다.

레퍼런스는 간결하고 정중해야 합니다.

요리법에 관한 비유를 다시 들자면 레퍼런스는 어떤 식재료에 대한 백과사전 항목과 비슷합니다. 해당 식재료의 성분, 기원, 효능과 화학적 구조, 조리법등을 담고 있죠.

레퍼런스에는 이 기능을 어떻게 사용하는지에 관한 기초적 설명이 꼭 포함되어야 합니다. 예를 들면 특정 클래스를 어떻게 인스턴스화 하는지, 어떤 메소드를 어떻게 호출하는지, 어떤 함수에 무언가 매개변수를 넘길 때 반드시 주의해야 할 점은 무엇인지 등등. 이런 점들이 레퍼런스와 하우-투 가이드를 구분짓는 차이점입니다. 소프트웨어의 정확한 사용법을 설명하는 것(레퍼런스)은 특정한 목적을 달성하기 위한 방법을 보여주는것(하우-투 가이드)과는 전혀 다릅니다.

세상엔 레퍼런스 말고 다른 종류의 문서라는 게 존재한다는 걸 상상도 못하는 개발자들도 있습니다. 그들은 이미 그들의 소프트웨어를 이해하고 있으며, 어떻게 사용하는지도 알고 있습니다. 그들은 다른 사람들에게 필요한 것도 오직 그런 기술적인 정보들일거라고만 여깁니다.

레퍼런스 문서도 보통 잘 작성되어 있는 편입니다. 심지어 자동으로 생성할 수도 있습니다(결과물이 항상 좀 허술하긴 하지만).

레퍼런스를 잘 쓰는 방법

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

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

일관적인 표현을 사용하세요

레퍼런스 문서는 다른 사전들처럼 구조, 어조, 형식등을 항상 일관성 있게 사용해야 합니다.

오직 설명만 하세요

레퍼런스 문서에 요구되는 유일한 기능은 바로 가급적 명확하고 완전한 설명입니다. 그 외의 다른 것들(해설, 논의, 조언, 추측, 의견 등)은 문서를 활용하기도, 유지보수하기도 어렵게 만듭니다. 혹시 필요하다면 설명을 위한 적절한 예제를 제공하세요

레퍼런스 매뉴얼에 기본적인 소프트웨어 사용법을 넘어서, 특정한 목적을 이루기 위한 응용법을 설명하고 싶은 유혹을 떨쳐내세요. 개념을 설명하고 싶은 욕심이나 개발과 관련된 사항을 논의하고 싶은 충동도 이겨내야 합니다. 대신 적절하게 하우-투 가이드와 해설 문서, 튜토리얼 문서들에 대한 링크를 제공하세요.

정확하게 작성하세요

이 문서에 포함된 설명들은 반드시 최신화된 정확한 내용이어야 합니다. 설명 문서와 실제 동작 사이에 존재하는 모순 유저의 꼭지를 확 돌게 만들고 말 것입니다.

해설 문서

해설과 논의는 특정한 주제를 명확히 하거나 주의를 환기합니다. 이런 것들은 문서가 커버하는 주제의 범위를 넓히는 역할을 합니다.

해설 문서는 이해 지향적입니다.

해설 문서는 어떤 면에서는 논의 문서라고도 할 수 있습니다. 이 문서들은 소프트웨어 자체에서 한 발짝 물러나서 더 넓은 시야, 혹은 기존과 다른 관점에서 소프트웨어를 바라볼 수 있게 해 줍니다. 여가 시간에 취미로 코드를 읽는 것 보다는 해설이나 논의를 읽는 게 일반적으로 덜 이상해보이겠죠.

이런 종류의 문서가 명시적으로 생성 되는 경우는 드뭅니다. 대신 문서나 코드 여기저기에 파편화된 해설들이 흩어져있곤 하죠. 가끔 해설 섹션이 존재하는 경우가 있긴 하지만 그런 경우에도 보통 '해설’이라는 제목이 아니라 대충 '배경 설명’이나 ‘비고’ 등의 제목이 붙어있고 제대로 된 해설이나 논의 문서로 기능하지 않기 일쑤입니다.

논의 문서는 생각보다 쓰기 쉽습니다. 누군가의 질문에 대답하는 게 아무래도 빈 종이에 무언가에 대한 설명을 써내려가는 것 보다는 간단하니까요.

특정한 목표를 달성하기 위한 방법(하우-투 가이드)이나, 사용자가 배우길 바라는 주제(튜토리얼), 작동 방식에 의해 정의되는 내용(레퍼런스)…등을 제외한 주제 중에서 당신이 한 문서에 담기 적당하다고 생각하는 내용들을 넣는 곳이 바로 해설/논의 문서입니다. 따라서 간혹 논의 문서가 다루는 주제는 좀 생뚱맞을 수도 있습니다.

해설 문서를 잘 쓰는 방법

맥락을 제공하세요

해설 문서는 배경과 맥락을 제공하는 곳입니다. 예를 들면 ‘Django를 통해 제어되는 웹 폼’ 이라던지 ‘Django CMS와 검색에 관하여’ 같은 것들이 되겠죠.

또한, 현재의 어떤 것이 왜, 어쩌다가 이렇게 된 것인지 (설계 단계의 결정 때문이었다거나, 어떤 역사적 이유가 있다거나, 기술적 제약 때문이라거나 등등) 그 이유를 설명할 수 있는 곳이기도 합니다.

대안과 의견들을 논의하세요

해설 문서에서는 여러 대안들이나 다각도의 접근을 고려할 수 있습니다. 예를 들어 Django 배포에 관한 문서라면 여러가지 웹 서버를 사용하는 선택지들에 대해 고려하고 평가하는 등의 내용이 있을 수 있겠죠.

논의 문서는 서로 반대되는 의견들을 저울대에 올릴 수도 있습니다. 예를 들면 ‘테스트 모듈을 패키지 디렉토리 안에 넣을까 밖으로 빼야 할까’ 같은 것들이죠.

무언가를 지시하거나 기술적 레퍼런스를 제공하지 마세요

해설 문서는 다른 문서들이 제공하지 않는 내용을 제공해야 합니다. 해설 문서는 유저에게 무언가를 하는 방법을 지시하거나 설명하는 곳이 아닙니다. 기술적인 설명을 제공하는 곳도 아니구요. 이런 내용들은 이미 다른 문서들이 해치운 부분이니까요.

이런 문서 구조에 관해서

분류가 왜 이렇게 애매하죠?

이렇게 명확한 분류 체계가 있음에도 불구하고 각 문서들이 애매하게 분류되고 서로의 영역을 자꾸 침범하는 데에는 이유가 있습니다.

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

	공부할 때 유용한 것	작업할 때 유용한 것
실용적인 단계별 목록	튜토리얼	하우-투 가이드
이론적인 지식	해설문서	레퍼런스

이렇게 각각의 영역들이 조금씩 겹치기 때문에 구분이 혼란스럽고 서로 섞여 버리곤 하는 거죠.

그러다보니 이 네 가지가 정확히 분류된 좋은 예를 찾기는 어렵습니다만, 꽤 많은 문서들이 이 네 가지 분류를 각기 다른 기능으로 인식하고 있다는 것은 어렵지 않게 확인할 수 있습니다.

Django(Django의 예전 버전들은 이러한 분류들을 명시적으로 사용하지는 않았었습니다)나 Django CMS 같은 몇몇 프로젝트들은 이 분류를 전면적으로 적용하고 있습니다. 두 프로젝트 모두에서 이러한 분류 방식은 가치를 입증해냈죠.

분석에 대해서

이 글에서 제시하는 문서화에 대한 분석은 다년간의 문서 작성 및 유지보수 경험과, 어떻게 하면 문서화를 더 향상시킬 수 있는지에 대해 고민하면서 보낸 많은 시간들에 기초하고 있습니다.

또한 이 글은 여러 분야에서 회자되는 원칙들에도 기초하고 있습니다. 예를 들어 튜토리얼에 대한 내용은 교육학의 기초적인 개념을 차용하고 있죠. 학습자와 선생을 배치하고, 소프트웨어 활용법을 마치 구체적인 작업을 하는 단계를 거침에 따라 일반적이고 추상적인 원칙과 개념을 익힐 수 있는 작업처럼 취급합니다.

문서화 작업하기

문서 작업자들의 가장 큰 두통거리 중 하나는 그들이 해야 하는 일이 뭔지 정확히 예측 할 수가 없다는 것입니다. 글을 쓰고 또 쓰지만 그럴 수록 흡족하게 글을 쓰기는 어렵다는 것만 깨닫게 되죠.

이 글에서 제시한 구조는 명확한 분류와 구분으로 그 의문점들을 해소해줍니다. 이 방식은 문서를 작성하고 유지보수하기 편하게 만들어 줍니다. 게다가 사용하거나 탐색하기에도 더 편리하죠.

여전히 문서화가 자동으로 되진 않습니다만, 이제 더 이상 뭔가 어색한 문서 분류나 내용의 애매한 범위, 대체 문서에 어떤 내용이 들어있어야 하는지, 이런 문서는 어떤 스타일을 적용해야 하는지와 같은 문제를 가지고 씨름할 필요가 없습니다. 뭘 써야 할 지, 어떻게 써야 할 지, 그리고 어디에 써야 할 지가 훨씬 명확해졌죠.

이는 사용자에게 더 나은 서비스를 제공하게 해줍니다. 이제 사용자는 소프트웨어를 사용하는 어떤 단계에서든 그 시점에 가장 적절한 종류의 문서를 확인할 수 있기 때문입니다.

명시적/암시적으로 이 네 가지 종류의 문서를 작성해 두는 것은 더 많은 사용자를 소프트웨어로 모아들이고 유지할 수 있게 해줍니다. 이 사용자들은 잘 분류된 문서를 통해 소프트웨어를 더욱 효율적으로 활용할 수 있게 되죠. 궁극적으로 모든 소프트웨어 개발자들이 꿈꾸는 목표가 바로 이 것이겠죠.

About the Divio Expert series

Our experts really do deserve the name. Between them they have decades of Django development experience; the depth and breadth of the expertise we are able able to offer is world-class. They include core developers of Django, django CMS and other notable projects, and the architects of very large systems such as the Divio Cloud infrastructure.
The new Divio Expert weblog series aims to share some of this expertise. For updates on new articles, follow our Twitter feed, or subscribe to our (very low volume) newsletter.

작성자 :

Daniele Procida
Author at Divio

역주 : 마지막 문단은 원본 시리즈에 대한 설명 및 홍보 멘트여서 원문을 유지해 두었습니다.