Two talks about documentation

In two recent conference talks, I learned about making better documentation. First, I heard Adrienne Tacke focus on the documentation's content, explaining how to make it more usable and effective. Then I saw Rich Harris go into how to build a documentation environment, showing a way to approach documentation of projects with a server-side components.

Both talks resonated with me. Good documentation is the backbone of every software project (and also crucial elsewhere, including for web standards like WCAG). For software companies there are countless business reasons to invest in documentation, and for anyone else, yes, improving documentation is still rewarding in many ways.

Types of documentation

To clarify what we're talking about here, Daniele Procida's Diátaxis framework for technical documentation, which I found out about in Rich's talk, identifies four types of documentation:

• tutorials, to teach people how to use the thing in the first place
• how-to guides, to teach an experienced user how to do specific things with your tool
• explanation, to give a high level overview of concepts in your tool
• reference documentation, to provide matter-of-fact information about functions, APIs etc, to be consulted not read; can be automatically generated

Adrienne's and Rich's talks focused mostly on the first two: tutorials and how-tos.

Be concise and valuable

In her talk, Documentation: the missing pieces, Adrienne went into some very common problems in documentation. She showed how documentation can be unclear and unhelpful, and then went on to show how to be concise and valuable instead. The whole talk is a must watch, but here are some highlights:

• be more explicit, by expanding acronyms (they can depend on context and not all acronyms are familiar to everyone) and by using the German naming convention (if you can be more explicit in a variable name, do it)
• be aware of the steps in what you are teaching and avoid skipping steps at all times; this is another moment of stepping (no pun intended) into the shoes of the reader of your documentation, they don't know your project as well as you do, so you want to be explicit and list all gotchas
• avoid surprises, always tell readers what they will need to make their way through the tutorial (prerequisities, dependencies, paid plans, time)
• focus on the thing you want folks to learn and help abstract the unrelated setup and configuration stuff away, by creating a starter app, Docker container or sandboxed environment, anything that isn't core to the thing you're currently teaching, but still needs to exist in order for the reader to get started

Interactive tutorials with a server-side component

In his recent JS Nation talk (start at 40s to avoid the crypto advertisement edited into the video 🥲), Rich explained tutorials are essential, as they actually show users what to do, but they are often overlooked. He showed Learn Knockout, a very early example of a tutorial he loved, and which the Svelte Tutorial was later inspired by, and others, like Lit tutorial, that follow the same model.

For the documentation of Svelte and SvelteKit, the frameworks he created, Rich used four principles:

• create a sandboxed environment, so that it is safe to make mistakes
• help muscle memory by disabling copy/paste (controversial!)
• provide a way to get straight to the solution if you're stuck (Rich calls this “panic button”)
• meet users where they are (in Svelte/SvelteKit's case: the browser)

Sandboxes for “full stack” projects need both a client and a server component. Some services provide a way to access a virtual server from a sandbox (like CodeSandbox Containers), but they have authentication barriers, to avoid abuse (like bitcoin mining) and can come with some latency, Rich explained. Then he found that on Stackblitz, the server is, rather impressively, ran inside the browser by compiling Node to WebAssembly and running that inside the browser's security sandbox (this is called WebContainers). And that wasn't enough: as he found a StackBlitz environment is made for coding, not learning, Rich teamed up with the StackBlitz team to have some kind of headless version of StackBlitz in order to create what's now in beta as learn.svelte.dev.

Summing up

While these talks were about different aspects of documentation, the speakers were equally determined to ensure that users of their documentation would actually learn the thing easily. It's not easy, neither when creating the content, nor in technically setting up the environment, but it can clearly make a difference.