Before jumping into things, it came up in this meeting that not everyone was aware of the slack channel that exists for this group. So I’ll leave it here for anyone interested in joining:
Reach out to me in an email if this invite link doesn’t work for you!
So what is documentation, exactly? On the surface it feels like a simple concept, but we very quickly realized as we jumped into our discussion that there are many different ways to define and categorize documentation - each of which comes with their own set of special circumstances.
In general, we identified a few broad categories of documentation. I’ve taken the liberty of pulling together a few ideas from the discussion into what I hope is a useful set of categories:
That first category, the reference documentation. There are a number of tools that exist for this; Doxygen and Sphinx are probably some of the common solutions (though not necessarily recommended ones). The more interesting question we had was: what’s the purpose of this type of documentation? Most of us agreed that in a proper development environment, reading source code or jumping around in the editor was more likely how we would read the kind of information found in these docs.
Reference documentation is often the first to be created, but for internal libraries and code bases - it’s arguably the least useful. The source code is readily available to all and doesn’t help new developers get introduced to the code base.
Following the train of though it seems like API documentation is much more powerful. Being something still very close to the code base, but with the time and energy being put in to focus on showing examples and explaining concepts to help the reader learn.
One of the clear downsides to such documentation, however, is that because it lives at a distance to the code it can very easily become out-of-date. If there’s one thing that we have all seen in our days it’s documentation that’s either old or just plain wrong.
One of the useful ways to handle this is through some form of testable documentation. The idea being that any code snippets or examples that you include in your documentation are somehow tested automatically alongside the code base. This way you can at the very least ensure that the examples being provided will work for those who try to leverage them. Jupyter Notebooks are one possible solution to this, at least for python APIs.
At the end of the day, all we really want is to have documentation that is helpful and useful to the people that need it - but how do we get people to read our documentation?
Perhaps the better question is: why don’t people read our documentation? It seems to us that there are 2 possible reasons: the documentation is not helpful to them; or they simply could not find it.
This may not be a particularly insightful affirmation, but it does speak to the frailty of documentation. It really needs to be exactly what people need in the exact place that they need it. We also spoke about reading levels here, which ties into the different documentation types mentioned above. Really understanding who a piece of documentation of for, and writing it to be as accessible as possible to exactly that audience is an important and very difficult thing to get right.
One recommendation that we talked through was having new hires read through documentation and examples, adding or fixing any problems that they encounter. This only really works for the type of introduction documentation that a new hire would read - but circles back to the idea of regular maintenance and upkeep of documentation that exists.
If your environment is anything like ours’, there are undoubtedly a few if not many sources of information about your software. Whether it’s the code itself; a ticketing system where users file bugs; internal technical discussions on tickets or in email; documentation pages for users, developers etc; readme pages in the repository; project reports and proposal documents in Google drive; and the list goes on…
Keeping all of this stuff up to date and having it available to anyone who might need it is probably a problem without a solution. We did however, pull out some useful ideas and recommendations that can help:
Having an easy way for documentation to get created, updated and released is definitely important. We also agree, however, that you simply cannot create good and useful documentation without a human touch. The same goes for release notes or any other form of communication that might be automated or go out regularly.
There was also a discussion about timing here. The default setup for automated systems is to notify people as soon as a change goes out and is available, but there is something to be said about delivering such information only after they are running the new version of the software. “You are using these new features now” is arguably much more relevant than “These new features are available when you or your production decides to update”.
That being said there are definitely still people who want and even need to know about new releases. Maybe they are the ones deciding to update, or they are the developer waiting for a bug fix. In reality, the solution is probably to have a few different delivery pipelines for the information - and leverage the process that makes the most sense for each user or class of user (aka: devs get release notes immediately and users get release noted the first time they run it).
We also talked about the parallels between news and docs. There are so many seemingly smart systems that try to find and deliver people relevant news from the internet, and our problems about documentation are not entirely dissimilar. Maybe we can learn lessons from the changing news industry about how people read and consume information these days… Really what we should all do is just start a podcast for each of our libraries, or just stream the whole development process on Twitch!
Thanks for reading!