What software documentation must address

↩ blog

← Previous: Literate Programming 2: Jumping from compiler errors to the literate program
→ Last: What software documentation must address

<2022-04-16T16:33:41+0530>

Before we proceed…if you don't see why documentation is important, read "Teach, Don't Tell" by Steve Losh, and come back here afterwards. The structure it suggests falls a bit short of the brilliance of the Diátaxis Framework, but nothing explains the need for documentation itself as well as "Teach, Don't Tell" and its analogies.

Now, on to the post.

Of late, I've been dealing with many projects where documentation is insufficient, or outright missing. This drove me write about subjects software documentation must cover.

Here's a basic list.

1. What the software is and what it does
2. How to install it (if applicable)
3. How to use it
4. How to customize it
5. How to build it (if applicable)
6. A high-level description of its implementation, and how it is organized as a program
7. How to extend it
8. How to test it
9. Technical reference of its implementation

This must be written for every level of the software, from the program/project as a whole to every component and feature, recursively.

That documentation cover all these aspects is important, especially in case of liberated software, which is released with the hope that it be used, extended, maintained, and remixed by complete strangers to the project.

There's a strong new-user->developer flow here. My attempt to adapt it to a Diátaxis Framework-oriented flow looks something like this -

1. Explanations
   • what it is and what it does
   • a high-level description of its implementation, and the organization of the the same
2. Tutorials
   • installation
   • usage
   • customization
   • building
   • extending
   • testing
3. How-to Guides
   • How to install the software
   • [Apply the skills taught in the Tutorials, as part of multiple, work-oriented recipes. See What’s the difference between a tutorial and how-to guide?]
4. Reference

I've seen people write just reference documentation, and skip how-to guides and tutorials. If you care about other people using and/or maintaining your library in the future, how-to guides and tutorials are important. Only you, the author of the library, know how to use it. Trying to decipher a how-to or tutorial from reference docs (or even example programs) is akin to

Documentation must be written and updated at the same time, and ideally in the same commit, as the implementation and the tests.

Where to store documentation - somewhere users expect it, and somewhere it's easily discovered (Gitea/GitHub READMEs). Centralize it as far as possible - minimize documentation-hunting for users.

That's what all documentation - and even all good design, software or otherwise - boils down to for me. Thinking about the user. Thinking about the next human…who might very well be you, a few months or years from now.

Documentation-driven design - writing docs first, code after. You can design, without bothing with implementation. It can guide your thoughts and your implementation.