3 learnings from our documentation workshop
Last week friday we held our first workshop by our documentation expert Daniele. Here's what we learned about software documentation.
First of all, we would like to thank you for the great interest in our first workshop led by the django CMS Association. We had over 20 participants and there were lively discussions among the attendees. Many thanks to Daniele Procida, who held the workshop and rightly received a lot of positive feedback for his presentation and the exercises that followed.
The picture above summarizes well the quintessence of the workshop. The basis of the framework for documentation presented by Danieles offers the division into 4 quadrants: Tutorials, How-Tos, Explanation and Reference. The distinct functions of these four different components of documentation were discovered by the participants themselves through their contribution to a collaborative exercise, in which they had to lend a hand ("Write a documentation (Tutorials, How-To, Explanation & Reference) about coffee").
If you are interested in the lecture and want to learn more about the framework, please watch this video:
Link: https://youtu.be/qC1OYK5oqDo
3 Learnings for the django CMS documentation
1. Completely rewrite the tutorials
Our tutorials need to be enriched with up-to-date code, following best practices for django CMS, and with simpler, quicker results for the user.
2. Bring documentation up to date with code
3. Removal of repetitive material
There is a lot of material that could profitably be jettisoned from right across the documentation, especially the rather repetitive material concerned with governance/community/contributing
To sum it up: Reduce, Simplify, Rationalise and Repeat
As you can see, there is a lot for us to do. If you feel like helping us out, join the "Documentation" working group and improve the django CMS documentation together with us.
Just write a short email to [email protected] and let him guide you through the process.
blog comments powered by Disqus
