문서화는 튜토리얼Tutorial/하우-투 가이드How-to guide/해설Explanation/기술 레퍼런스Technical reference 등 네 가지의 역할 중 하나에 속해야 하며 거기에 알맞는 구조를 가져야 합니다. 문서는 명시적으로 이들 중 한 가지의 구조를 가져야 하고, 다른 종류의 문서들과 명확하게 구분되어야 합니다.
튜토리얼은
- 학습 위주로 이루어져 있고
- 뉴비가 제품 사용을 시작할 수 있도록 해주는
- 강좌입니다. 비유하자면, 어린 아이에게 요리법을 가르치는 것과 비슷합니다.
하우-투 가이드는
- 목표 지향적이고
- 특정한 문제를 해결하는 방법을 보여주며
- 여러 단계로 이루어져 있습니다. 요리책에 쓰여진 조리법을 떠올려보세요.
해설 문서는
- 이해를 기반으로 하며
- 설명하고
- 배경 지식과 맥락을 제공합니다. 요리의 역사에 대한 기사를 생각해보세요.
레퍼런스는
- 정보를 중점으로
- 동작을 기술하며
- 정확하고 완전한 내용을 담고 있습니다. 백과사전 항목을 떠올려 보시면 됩니다.
이러한 구분은 작성자와 독자 양측에게 정보의 향방에 대한 분명한 예측을 가능하게 합니다. 작성자 입장에서는 무엇을, 어디에, 어떻게 써야 하는지에 대한 지침이 됩니다. 그럴싸한 문서를 만들어내기 위해 수많은 정보들과 씨름하는 고통에서 작성자를 구해주는 것이죠. 각 종류의 문서는 각각 단 하나의 목적만을 가지고 있으니까요.
사실, 명시적으로든 암시적으로든 이 네 가지 중 하나로 분류되지 않는 문서는 관리하기 어렵습니다. 각각의 문서는 다른 문서들과 완전히 다른 요구사항을 가지고 있기 때문에, 이러한 분류 체계를 유지하지 못하는 문서를 관리하는 것은 마치 한 번에 사방팔방으로 줄을 모두 당기려는 것과 같습니다.
일단 이 분류 체계를 이해하게 되면, 이미 존재하는 문서들을 분석하고 어떻게 그 문서들을 향상시킬 수 있는지 이해하는 데에도 아주 유용한 지식이 될 것입니다.
하우-투 가이드는 순서대로 따라야 하는 단계별 목록을 제시합니다(튜토리얼과 흡사합니다). 굳이 아주 초보적인 부분보다는 적당하다고 생각되는 부분을 시작점으로 선택할 수 있습니다. 하우-투 가이드는 신뢰할 수 있어야 하지만 튜토리얼처럼 반드시 반복 가능해야 하는 견고한 구조까지는 필요하지 않습니다.
하우-투 가이드는 실용적인 목표에 집중해야 합니다. 그 외의 다른 것은 모두 부차적인 문제입니다. 튜토리얼에서와 마찬가지로, 과도한 설명은 지양해야 합니다.
하우-투 가이드는 반드시 특정한 문제나 질문에 대한 해답을 제시해야 합니다. 이 문서는 “ㅇㅇㅇ을 하는 방법” 이니까요.
이 점이 바로 하우-투 가이드가 튜토리얼과 차별화되는 부분입니다. 하우-투 가이드를 읽는 독자는 자신이 하고자 하는 게 무엇인지는 이미 짐작하고 있습니다. 다만 구체적인 방법을 모를 뿐이죠. 튜토리얼에서처럼 당신은 독자가 해당 문제를 해결하기 위해 무엇을 알아야 하는지를 결정할 책임이 있습니다.
하우-투 가이드는 뭔가를 설명하지 않습니다. 그런 종류의 논의를 하기 위한 무대가 아닙니다. 하우-투 가이드에서는 단순히 행동을 나열하면 됩니다. 만약 중요한 설명이 필요하다면 해당 설명에 대한 링크를 제공하세요.
하우-투 가이드는 같은 일을 하기 위한 여러가지 다른 방법들에 대해 유연한 태도를 가져야 합니다. 여러 비슷한 경우들에 대해 제시된 내용이 어떻게 적용이 가능한지 유저가 알 수 있을 정도, 혹은 비슷한 다른 시스템이나 환경에서 어떻게 이 방법을 적용할 있는지 알 수 있을 정도면 충분합니다. 너무 특정한 상황에서만 들어맞는 문서는 정확히 동일한 상황이 아니면 쓸모가 없겠죠.
완벽한 것 보다는 실용적인 것이 중요합니다. 튜토리얼은 완성도가 높고 처음부터 끝까지를 제대로 설명해야 하지만 하우-투 가이드는 그럴 필요가 없습니다. 하우-투 가이드는 시작와 끝을 적당히 정해도 됩니다. 주제와 관계된 것이 있다고 해서 굳이 그 것들을 모조리 언급할 필요도 없습니다. 내용이 너무 빵빵한 하우-투 가이드는 유저에게 빠른 해결책을 제공하지 못합니다.
하우-투 가이드의 제목은 이 문서가 무엇을 설명하고 있는지를 정확하게 드러내야 합니다. ‘클래스 기반 뷰를 만드는 방법’ 은 좋은 제목입니다. '클래스 기반 뷰 만들기’는 좀 애매하네요. '클래스 기반 뷰’라는 제목은 영 별로입니다.