How to document your application. Best Practice
As a Developer, documentation is way down on the list of my favorite tasks, but its way too important to ignore. I’m not going to go into different software packages or compare to inline and in code documentation here, but talk about how we document applications to make then ready for users, and not just other programmers.
Before we start, I want to introduce Daniele Procida, the person who’s ideas I’m sharing here. My wording might not be the same as his, but the concepts are basically the same.
Diátaxis documentation framework.
The Diataxis framework was created by Daniele and it makes perfect sense, especially when your struggling to write documentation that is to be presented to users/customers, and developers.
As you can see from above, the idea is to see documentation from four different points of view. The second thing to note is that you should stick to the four quadrants and not to mix them up. This is really important. We struggle with user documentation because we end up mixing the documents requirements together and the end product is not good.
Tutorials
Your looking at the chart above and your thinking that tutorials and How To guides are similar or the same thing. You are also thinking that explaining the concepts of the application might also be in the tutorials as well.
Now you start to see an issue. A tutorial that is a How To with concepts and explanations, will just being a total mess.
Tutorials should be nice simple guides to using specific functions of your application. They should be step by step, and based on general concepts. They should also be about the application and its use. No specific use cases.
How To’s
How To’s need to address specific user needs. Instead of a general introduction to functionality, they should take a specific need and given a guide to dealing with that need. As an example, you could have guides to using and setting up Nginx, but as a How To, you give a guide to setting up Nginx for use with Django and Gunicorn. The How To will skip a lot of the details of dealing with Nginx because they are not relevant to dealing with your needs when setting up Django. You only need the parts relevant to your task. The same would go for Gunicorn.
I hope you are starting to see the difference in the quadrants now and why they need to remain separate.
Explanations or Concepts
The Application you have built was most probably built on a set of firm concepts and business requirements. These could be fairly deep in nature. Take https://flown.com for example. The application isn’t really all that complex, but the psychology behind it is.
This app also uses WebRTC (I think), so there is another concept you will want to explain. These are not really needed for users to be able to use the application, but they do need to be explained to the users. The use of WebRTC would also need to be explained for future developers of the app.
Reference.
This is the part of the documentation you will be most familiar with. This could be built using something like Sphinx to gather docstrings, or written by hand. Here you explain the classes and API’s in the code. If your focused only on customers, you might want to limit access to this, but in other cases, this would where developers come to find the fine grained details of the application.
Conclusion
Since I first watched Daniele on YouTube talking about this, I’ve been a fan. Writing documentation for customers, other users and developers is just not that easy, when you see everything from a developers point of view. His explanation just makes sense. I still end up writing documents that blur the line, but I then go back and fix them so they don’t. This idea really does make documenting properly much easier and gets betters results.