One thing that I seem have been able to impress upon the people I’ve worked with is my keenness for writing technical documentation. I don’t mean to say that I am in any way an expert on it, but I have always been adamant that it must be present, and it must be good. I’ve seen far too many instances of tomes of written word on a highly technical subject, describing all the intricacies of its subject matter, only to rot away in a digital purgatory of forgotten Confluence pages or unmaintained GitHub wikis.
In my experience, good technical documentation is hard to write. We, as developers, are often required to write such documents, though as authors we may not necessarily think that we might one day be their consumers. After all, if I am knowledgeable enough on a subject to describe it in detail, it’s difficult to imagine a situation in the future where I may need to review my own descriptions of it.
Well, those of us who have been in that situation know that it is an inevitability for every programmer to forget. Just forget, in general. Doesn’t matter how self-confidently sure we were of ourselves in the past that what we had produced as source code would never leave our endless vaults of memory, we’ve all experienced moments in our careers where we’ve gone “Oh nuts, if only I had written this down somewhere…”
Prioritizing information Link to heading
To begin with, lets talk about UI/UX for a moment. More specifically, lets consider the way our eyes and minds consume information from a rectangular area:
This is known as the Gutenberg Rule1, or the “F-pattern”2, and its name comes from the fact that the way our eyes scan a webpage generally follows the shape of the letter F. We start from the top-left corner, then move right. Afterwards, we jump to the next row of elements ( or text ), and scan through those, but not with the same rigour as the first row ( notice how in some fonts, the second horizontal line in the capital letter F is shorter ). Generally speaking, our eyes will hyper-focus on the top-left, and our attention to what’s happening in the bottom-right will be far more lacking.
Why is this important? Well, think about what writing documentation actually is. In essence, the author is creating a webpage. Yes, it may be as part of an already existing platform ( such as Confluence or GitHub ), but it’ll be rendered on the viewers screen just like any other website. As authors, we have to take this into account and structure, or prioritize, the information we want to show the reader.
Always start with text Link to heading
What I’ve found works well is if the page always begins with some sort of introduction. Don’t just jump into the nitty gritty technical details right away. The readers eyes might be in the right place, but their brain is likely not prepared to consume the raw information we wish to provide them. It’s akin to foreplay, allow the mind to slowly get on board with the idea of “hey, it’s reading time, you have to focus now”. This also gives you the opportunity to provide a concise description of what it is the article is about.
Note: For the duration of this post, I’ll be using examples of what I consider to be good documentation practices. One of my favorite ever resources is the wiki for Multi Theft Auto, a multiplayer mod for GTA: San Andreas ( https://wiki.multitheftauto.com ).
Have structure. Use headers. Link to heading
As can also be witnessed in the screenshot above, giving structure to your documentation can do wonders. Remember, the eye tends to wander from top to bottom, so giving it nice large headers to stop at is a good way to direct the attention of the reader to the various constituent parts of the article.
And on that note, having a standardized format is also a very good idea. Of course, not all types of documentation can benefit from using the others structure, so in such cases you ought to identify categories of documents and each category ought to have a different standard structure. It’s like having a style guide for your code: when it all “looks” the same, the reader only has to learn it once, and can then focus on the contents rather than trying to make sense of each new articles format first.
If you need to list, use a list. Link to heading
HTML provides various types of DOM elements for different use-cases. If you need a paragraph, there’s <p></p>, if you want a link there’s <a></a>, or if you want a list of stuff, you have various different options, the most basic of which is <ul></ul> and <li></li>. Technical documentation will often times require all of these elements at once, making each article a potentially complex collection of different sorts of data that need to be presented to the reader in the most eye-friendly way possible.
Confluence and GitHub both use markdown, which itself has support for all of these elements, and more. Having an awareness of what it is you need to describe and in what format is invaluable to writing concise, readable documentation. The previous screenshot from the MTA wiki shows this off beautifully, where you can see lists being used for the arguments of the function. A little lower down, it’s also used to display various functions related to the one the article is about:
Friends don’t let friends read code in plaintext Link to heading
There is nothing more frustrating to me than having to read code without highlighting, rendered in a non-monospaced font, without any proper formatting. If I had to guess, reading code in this way probably increases the time it takes to comprehend the contents tenfold. If it’s just a single token, inline formatting is fine, but anything containing a whole function declaration ought to be in its own code block.
Provide examples! Explain them! Link to heading
Every single developer who’s had to deal with lackluster documentation has had this feeling of genuine annoyance with an author who explains a concept, maybe shows some tiny snippets of code, but never provides a full in situ example. Theory and technical details are great and all, but I would reckon 80% of the people reading a piece of documentation need first and foremost to get a more general grasp of the concept being described.
In the previous screenshot, the MTA wiki shows this off well, with a fully fledged self-contained function, along with an example of its use. Not only that, but the author has provided comments further explaining parts of the code which the reader may not be aware of.
Often times when I write comments, I get a sense of futility. This is because I feel like I’m describing something which is self-evident from the code itself. Well, I’m sorry to report that the concept of “self-documenting code” is, in my mind, fundamentally flawed. No matter how standard the conventions, or how well-accepted the rules, there will come a time when someone who isn’t aware of them will have to read your article. To add to this, there could also come a time when the conventions change. What happens to self-documenting code then? Do we go back and redo every line written with the old conventions, simply to maintain this idea of self-documentation?
Hanging on to an ideal like “conventions should never change” is also entirely unrealistic, as anyone who has worked on legacy enterprise projects will attest to. 20 years ago, we wrote code one way, and now we write it differently. Yet, the project is the same, except now the old “self-documenting code” is no longer legible because the people who wrote it either retired or moved on to a new position somewhere else and took their conventions with them.
This doesn’t even cover the other flaw with self-documentation, which is that code can only attest to the “how”, and never the “why” of its construction. The intention behind a piece of programming will forever remain in the mind of its creator unless it is explicitly described in a comment.
Structure your knowledge base Link to heading
Going outside the scope of a single article, the way the overall knowledge base is organized is also crucial. The ability to search is often times not enough, or even not present at all. Of course, if it is, providing your search engine relevant metadata for each article should also be a priority. Think search engine optimization, but for your own collection of web pages.
In my mind though, having a well laid out design to your entire wiki can be enough by itself to give any reader an easy time of finding exactly what they’re looking for. Meta-articles are vital here, and they can be important routing mechanisms to direct the user in the right direction.
This single little section in the left-hand menu of the MTA wiki is all I have ever needed to find 99% of articles. It contains 9 pages, each of the “meta” sort I mentioned. All of them are really nothing more than just a giant list of other articles. Of course, if the software you use supports other methods of getting this sort of thing done, don’t just go replicating what the MTA team has done here. However, one huge benefit I will mention is that because all the contents of each article are rendered upon opening, it is supremely easy to simply Ctrl+F search the specific function I want, or think I might want.
It also contains so many other things, that if I was uncertain of what I want, I can just as simply browse through the hundreds of functions described here so I could find what I need.
A home page Link to heading
Lastly, on the topic of general knowledge base structure, I would like to mention the importance of a nice home page. As a potentially new user, how would I know where to go unless I am directed to go there? Well, I wouldn’t, and the moment I open up a wiki which just thrusts me straight into whatever happens to be the first article of a series, I would be very confused.
Having this initial landing page here, the MTA wiki manages to collect all of the important subjects it has articles on in one place. It can do this, because the authors have painstakingly taken the time to categorize every article, and sort it into an appropriate folder. From there, each category becomes a wide discussion topic, with several specific points being discussed within as articles. Ultimately, this leads to the creation of a sort of tree structure, carefully guiding the reader from the general to the particular.
Conclusion Link to heading
Maintaining a knowledge base is hard work. Unfortunately for developers, there’s nobody else to do it other than us. We are the only ones aware of what needs documenting and how, and so we have to take the responsibility for it. However, it is also the duty of those in charge of a project to understand that this is a meticulous process which shouldn’t be ignored, so ample time ought to be provided not only for writing and testing code, but also for documenting it. It’s not only in our own personal interests, to avoid wasting time explaining concepts a thousand times over, several times a year to the new litter of junior developers or interns, but also in the interest of whoever it is that benefits from the overall project development running smoothly. Nobody benefits from a bus factor of 1, and comprehensive documentation is key to improving the overall efficiency of development.