Feb 22, 2021
OwlDocs: How not to document your software library
Why writing good software documentation actually saves time
Imagine you’re a beginner at knitting and you want to knit a jumper. You open your knitting pattern, and the first page shows you how to do a basic row of stitches — so far, so good. How would you feel if the next page told you how to knit an arm (but not the front or back or how to put it together), or worse still just gave the instruction “now knit the rest of the jumper”. This happens all the time with software libraries. Head over to the docs and there’s a perfectly reasonable “Hello, world” example. Straight after that, it drops off a cliff. I like to refer to documentation like this as “OwlDocs”, after the meme which suggests you learn to draw an owl by drawing a circle and then drawing the rest of the owl. (I’m paraphrasing, the meme isn’t that polite.)
Often docs contain lots of snippets of code aimed to help people use functionality beyond the initial basic example of the library. However to keep them short, these usually lack basic wrapper code that would be required to use the snippet in practice. That’s really tough when it’s the first time you ever use the library. I tried one particular library for the first time recently and its ‘Hello world’ example was a program which executed beautifully. What they failed to tell you in the docs was that to see the output you had to open a web browser and look at localhost, port 8888. I managed to figure that out given the code, the context and the knowledge I had, but why wasn’t that explicitly written in the docs?
Some people may say “well if you can’t figure out how to use the library, it’s probably because you’re not good enough at programming to use it”. I reject that statement. It is absolutely true that some pieces of software are much more complicated (and necessarily so) than others. For example, I wouldn’t expect to become fully acquainted with how to use a sophisticated machine learning library in minutes from reading the docs. However, that does not excuse the documentation being full of plot holes. If the software is sufficiently complicated that the user needs to expend time and effort in order to understand how to use it, it is also essential that the documentation doesn’t require knowledge that literally isn’t written down anywhere except inside the dev team’s collective consciousness. Good docs don’t hinder experts.
The quality of software documentation is even more crucial for software that is aimed at beginners. I started writing the guizero Python library shortly after giving a talk at Pycon UK 2016 which touched on how getting started with software libraries was often an unfriendly experience for people with little peripheral knowledge. (I also admit in this talk that, at the time, I didn’t know how to use pip!) It was very important to me that the documentation was clear, comprehensive and provided a gentle ramp to getting started with the library. Whilst advanced users will probably feel inconvenienced if the docs aren’t great, beginners will be excluded.
Clear, friendly and comprehensive documentation helps everybody. It helps beginners get started and gradually improve. It helps more experienced developers quickly find what they need to know. It even helps the developers of the library — I can’t count how many times I’ve forgotten something about guizero and gone back to look it up in the docs. Writing documentation might not be the most exciting part of writing software, but don’t make your docs an afterthought.
