There is a secret that needs to be understood in order to write good software documentation: there isn’t one thing called documentation, there are four. They are: tutorials, how-to guides, technical reference and explanation. They represent four different purposes or functions, and require four different approaches to their creation. Understanding the implications of this will help improve most documentation - often immensely.
I dig Daniele Procida’s take on writing good software documentation. It just makes sense. The system is simple, comprehensive, and, crucial, universally-applicable. The “four different functions” scheme works equally well if you are writing for a technical-savvy audience or the general public, which is excellent. The users I’m writing for are software developers, in some cases, and desktop or web application users in others.
I also like how he goes deep into explaining how and why each function has a different goal, should be isolated and written differently from others.
Each of them requires a distinct mode of writing. People working with software need these four different kinds of documentation at different times, in different circumstances - so software usually needs them all, and they should all be integrated into your documentation. And documentation needs to be explicitly structured around them, and they all must be kept separate and distinct from each other.
Last but not least, the framework itself serves as a guide for the author.
This division makes it obvious to both author and reader what material, and what kind of material, goes where. It tells the author how to write, and what to write, and where to write it. It saves the author from wasting a great deal of time trying to wrestle the information they want to impart into a shape that makes sense, because each of these kinds of documentation has only one job.
I wish I had this resource at hand when I was writing the docs for my open source projects. I think will adopt this framework on the next occasion, which will be very soon.
@nicolaiarocci on Twitter*