[RFC] 2 WIP: Documentation Framework

[frankhinek]

• RFC Name: Documentation Framework
• RFC ID: 2
• Start Date: 2022-08-22
• Contributors: @frankhinek, @ALRubinger
• Current Status: WIP

Summary

Proposal to adopt a documentation structure that organizes material along two axes of knowledge, theory/practice and acquisition/application, with four distinct types: tutorials, how-to guides, technical reference and explanation.

Context and Scope

This proposal is heavily influenced by the Diátaxis systematic framework for technical documentation authoring by Daniele Procida used under CC BY. Rather than paraphrasing the author's thorough research and writing on the subject of technical documentation authoring, I'll quote directly from the framework and would encourage community members to visit the Diátaxis site to learn more. Daniela maintains a long list of projects, products, and organizations that have adopted this framework.

The problem of structure

Of all the problems that bedevil authors and maintainers of documentation, the problem of structure is one that accounts for a significant proportion of the grief they suffer. Multiple different documentation architectures exist that try to provide a solution to this problem. Any orderly attempt to organize documentation into clear content categories will help improve it (for authors as well as users).

However, even when armed with a helpful structure, authors often find themselves needing to write particular documentation content that seems to falls outside the scheme it provides, or across its internal boundaries. organizing material this way is that it provides both clear expectations (to the reader) and guidance (to the author). It’s clear what the purpose of any particular piece of content is, it specifies how it should be written and it shows where it should be placed.

The map

Diátaxis aims to solve this problem by providing a scheme that prescribes documentation structure based on a systematic description and analysis of user needs (and not upon the characteristics of the product documentation is intended to serve, or around the different kinds of things that the documentation creator feels need to be said about the product).

Diátaxis provides a map of distinct documentation types rather than a mere list, and specifies these types in such a way that the structure always naturally helps shape the content into an appropriate form.

Axes of knowledge

It’s important to understand that Diátaxis is intended to apply to documentation pertaining to a practical craft, a technical skill - such as the use of a product. Successful exercise of any such craft or skill involves both theoretical grasp (knowledge and understanding), and an ability to apply that in practice, to work with the tools and materials of the craft.

Diátaxis divides documentation across two axes of knowledge: theory/practice, and acquisition/application.

Documentation therefore either contains theoretical knowledge or describes practical actions, and is concerned either with serving our acquisition or our application of knowledge. Hence the map, across which the four forms of documentation are laid out:

Characteristics of documentation

A clear advantage of organizing material this way is that it provides both clear expectations (to the reader) and guidance (to the author). It's clear what the purpose of any particular piece of content is, it specifies how it should be written and it shows where it should be placed.

	Tutorials	How-to guides	Reference	Explanation
what they do	introduce, educate, lead	guide, demonstrate	state, describe, inform	state, describe, inform	explain, clarify, discuss
answers the question	"Can you teach me to...?"	"How do I...?"	"What is...?"	"Why...?"
oriented to	learning	tasks	information	understanding
purpose	to allow the newcomer to get started	to show how to solve a specific problem	to describe the machinery	to explain
form	a lesson	a series of steps	dry description	discursive explanation
analogy	teaching a child how to cook	a recipe in a cook book	a reference encyclopedia article	an article on culinary social history

Each piece of content is of a kind that not only has one particular job to do, that job is also clearly distinguished from and contrasted with the other functions of documentation.

Collapse of the structure

Most documentation systems and authors recognize at least some of these distinctions and try to observe them in practice. However, there is a kind of natural affinity between each of the different forms of documentation and its neighbors on the map, and a natural tendency to blur the distinctions (that can be seen repeatedly in examples of documentation).

• tutorials and how-to guides both describe practical steps
• how-to guides and technical reference are both concerned with the application of knowledge
• reference and explanation both contain theoretical knowledge
• tutorials and explanation are both concerned with the acquisition of knowledge

Allowing these distinctions to blur is what brings about structural problems. The most common is a complete or partial collapse of tutorials and how-to guides into each other, while explanation spills over into both tutorials and reference material.

The cycle of interaction

Diátaxis is intended to help documentation better serve users in their cycle of interaction with a product.

This phrase should not be understood too literally. It is not the case that a user must encounter the different kinds of documentation in the order tutorials > how-to guides > technical reference > explanation. In practice, an actual user may enter the documentation anywhere in search of guidance on some particular subject, and what they want to read will change from moment to moment as they use your documentation.

However, the idea of a cycle of documentation needs, that proceeds through different phases, is sound and corresponds to the way that people actually do become expert in a craft. There is a sense and meaning to this ordering.

• learning-oriented phase: We begin by learning, and learning a skill means diving straight in to do it - under the guidance of a teacher, if we're lucky
• task-oriented phase: Next we want to put the skill to work.
• information-oriented phase: As soon as our work calls upon knowledge that we don't already have in our head, it requires us to consult technical reference.
• explanation-oriented phase: Finally, away from the work, we reflect on our practice and knowledge to understand the whole.

And then it's back to the beginning, perhaps for a new thing to grasp, or to penetrate deeper.

Goals

• Make it easy for anyone to contribute documentation by providing common templates, starting with Tutorials and How-to guides.
• Incorporate a summarized version of this guidance into the TBD GitHub repository for community-contributed documentation to guide authors in better serving the needs of readers by considering the purpose and structure of their content.
• Pragmatically incorporate the philosophy of this framework into the UX/UI design of the learning/education section of developer.tbd.website in a manner that is useful to the community, appropriate given teh current stage of project development, and adaptable as needs change.
• Socialize the distinction between tutorials and how-to guides.

Non-goals

• Dogmatically applying the philosophy of the any framework to TBD documentation. Pragmatically applying the lessons that work for the TBD community is the objective and not necessarily dividing all documentation into four sections or using a UI layout with four headings.
• Being the final word on TBD technical documentation. The approach and content should adapt to the changing needs of the projects and community of contributors and commercial partners. Documentation for active projects and a thriving community can always be further developed and improved.

Proposal

This proposal is still a work in progress pending feedback and discussion with TBD and community members on the concepts of philosophy of how to organize and structure technical documentation. This proposal will be updated as we iterate and form consensus.

To realize the goal of making it easy to contribute tutorials and how-to guides by following a common template, the following outlines are proposed. These initial template can serve as prototypes to iterate on and get feedback from the community. The templates and accompanying guides were created and published by The Good Docs Project and used under the Zero-Clause BSD license.

Tutorial Template

• Tutorial Guide
• Tutorial Template

How To guide Template

• How To Guide
• How To Template

Definition of Success

• Documentation contribution guidance is expanded, incorporating consensus from the reviewers of this proposal.
• Tutorials and How-to guide template is published to a publicly accessible repo.
• Positive feedback is received from the community regarding documentation quality, measured by the degree to which documentation:
  • helps readers accomplish their goals
  • is accurate, up-to-date, and comprehensive
  • is findable, well organized, and clear.

Open Questions

1. How is TBD thinking about where and how to incorporate community-contributed tutorials, etc. into developer.tbd.website? Presently, educational content is published to both the Learn and Blog sections. Should a new section be added? Should Learn be modified?

[saeedjabbar]

Excellent write up! I do think Learn should be modified for education content. The current content on learn seems more appropriate for the Blog.