chrischinchilla

4 min read - Posted 20 Nov 19

Why write documentation

What's one of the first things you look at when you look at using a new project?

It's likely some form of documentation. Whether it is official documentation, or external blog posts, videos, books, or even code comments.

Ideal documentation should contain everything someone needs to get started with a project without having to read the code.

In the words of the creator the Perl language, Ken Williams.

Documentation is complete when someone can use your project without having to look at its code.

But when was the last time you read documentation that was complete, where everything worked, it was clear, and it addressed your exact questions and needs?

I don't mean to criticise those who write documentation. It's a hard task. It's hard to keep up to date, it's hard to address every use case and combination of tools that a reader may have, and typically, small projects do not have a dedicated team member handling documentation.

Documentation has many readers

It's not just developers who read documentation. Yes, it's mostly developers, but also developer's colleagues and bosses read it when making decisions about paying for or using software. More crucially, machines read it. Well written documentation means that systems that parse content can also make sense of what you've written, which is especially useful for searching your documentation, and people finding your documentation via search engines.

Assume nothing

Assumptions are unhelpful, often inaccurate, and annoy readers. Documentation should remove technical assumptions, and assumptions made about the reader.

Technical assumptions

Developers often tend to assume that every other developer has the same setup as them, with the same dependencies, and dependency versions. We all know this is not true, and we have all encountered dependency hell, with tangles of (often surprising) dependencies blocking us from installing something until we figure out the problem and what specific packages fix the nightmare.

When writing documentation, test all your assumptions. This takes longer, but like many things, in the long run, it saves you and your users time. Use tools such as virtual environments (if the language supports them), Docker or virtual machines to test fresh setups, and follow the same process for any operating systems you intend to release for. You can automate much of this work, which you can also use for testing your code, but there's no reason not to tie this code testing and documentation together.

About your reader

The next assumption is around who your reader is, and what they may know. We'll cover writing inclusive language later, but in summary, not every reader is like you. 'Developers don't all learn their craft in the same ways. Not all spent 3-4 years studying computer science. Many (possibly like you reading this) learnt through short, intense coding courses or boot camps. These shorter courses often teach students how to code practically, but not so much theory on topics such as design patterns, assembly language, or underlying principles.

Documentation is not the place to show off how smart you are and how much you know. It is the place to explain to users how to use your project. If you need to explain complex theory because it is essential to understanding your project, then include it, and supply explanations and background to these concepts. You don't have to write these (unless they don't exist anywhere else), links to quality external resources are fine.

This is especially an issue in the Web3 space. It's an ecosystem full of new terminology, and (some) new technology, or new interpretations of old technology. There are concepts fundamental to Web3 such as consensus algorithms that are hard to explain, but are not as new or unique as we think, and we can learn from previous efforts to explain them in other ecosystems.

There are ways to explain complex topics without blinding people. You abstract some detail, but that's fine. We'll look at the best places to explain what level of technical detail in the next post.

Created with Sketch.Content is"CC-BY-SA 4.0" licensed
Article On-chain
0 Comments
Related Articles
Documentation structure

Documentation structure applies to your documentation as a whole, and to each page. Lets start at the top and work down. There are different types of documentation your project might need. The terms I use to describe them below are just the terms I use, and others use different terms. The explanation of what they are is more important than what you decide to call them is up to you. Documentation types Getting started A Getting started guide is often a starting point with your project. It should

Chris Ward

14 Nov 19

Language and understandable writing

I appreciate that not everyone who writes documentation is a native English speaker, or even if they are, may not understand the best way to write clearly and concisely. Many native English speakers had our last grammar lesson more than 20 years ago, and have learnt the tips and tricks we now use as professional writers recently. There are three important things to remember to justify the time and effort of making your writing more understandable: English is often a default language for technica

Chris Ward

18 Nov 19