Many programmers, including myself, are self-taught. Some switch to programming from other, less-technical, careers. This can sometimes mean that they need to start with the basic knowledge that others may assume already is known. When writing documentation it is easy to forget that what was learned over our careers may seem incomprehensible to others.
Speaking of the basics, where do we get this information? For a self-taught programmer, such as myself, there are a few possible ways. Maybe we sit through free computer science classes. Some of us cram a lot of programming books. And some, like myself, take the Wikipedia route.
The Wikipedia Method of Documentation
What is the Wikipedia route? Science tells us we aren’t as good at multitasking as we like to believe. We aren’t exactly perfect at remembering things either.
My personal style of learning means that if I don’t learn something in the process of solving a problem, I don’t remember it. That means I tend to learn “on the fly”, or when that knowledge is needed for what I am trying to figure out. This frequently means I’m jumping from subject to subject, learning what all the different terms that are being used in the programming industry mean.
Wikipedia is a good example of a helpful resource because it links to everything. Very similar to a mind map, each node, or topic, leads to others. Since our brains work this way, why doesn’t our documentation?
For example, many programming learning paths recommend TDD (that’s Test Driven Development, by the way), because it’s a great way to avoid forgetting to test your code, and it’s really helpful in making sure your code does what it’s supposed to. An important part of testing is ensuring you have a good level of code coverage.
What’s code coverage? Well, let’s see here. We are going to do an experiment. Take a look at https://en.wikipedia.org/wiki/Code_coverage. Wasn’t that helpful? Oh, wait. I forgot. Pretend that you can’t click any of the links on that page. Any of them. None of those words were linked. Did it still make sense?
For those of us who are _only_ a https://1x.engineer/, that article probably would have sent you down a search rabbit warren looking up terms and concepts that were linked. Pretty helpful, right? How much harder would it have been if Wikipedia didn’t link to all those related articles or added references?
Why doesn’t our technical documentation do the same? Sure, there are API (application programming interface) manuals, like https://javadoc.io/doc/io.sentry/sentry/latest/io/sentry/package-summary.html, but we are talking about guides telling us what it is and how to use it. The quick install guide for the Django web framework is another nice example of several links. Here’s the definition of “web framework”, by the way.
How to Improve your Docs
Now, let’s take a look at ways to improve. I’ll use Getting Started with Code Coverage for Golang as an example. Take a quick look. Note how words like “Golang”, (Sorry, Tom, it’s just “Go”), “uploader”, and “flags” are linked. You can follow those knowledge threads to learn more about the topic, without having to search through the flood of information online, which can get really overwhelming and time-consuming. Adding context through linking spares programmer time and frustration, which makes the documentation easier to use.
So, as we like to say online, TL;DR (Too Long, Didn’t Read): Write your documentation as what you would have wanted to see when you were starting out on your technical path. Link more! Enhance the learning!
And, as I like to say in support: “If all goes well, we’ll never talk again!” 👋
