Last week in the Djangonaut Space, we had a session with Daniele Procida called Let's become confident about Django documentation, right now. This session brought back something we discussed during the DjangoCon US 2023 Sprints.
Documentation
Documentation is a form of art. Drawing words from thin air and placing them sensibly in a document or tool of your choice to achieve a predefined goal.
Let's say I am learning Django for the first time. The first thing would be to look for step-by-step documentation (tutorial) and follow someone along to build a CRUD project. After a few trials, I learned how to build Django projects. With the knowledge I have acquired, I decided to add authentication using sign-in with Google. The next thing is to do research on how to implement sign-in with Google on a Django project. By the end of the article, I will have implemented this. However, now I am curious to know if there are different ways to implement this and if how I implemented it is the right way (reference). Now that I have learned the different ways and settled on the right way, I want to understand why most applications have moved to using single sign-on instead of email sign-ins (explanation).
As per the above ideal analogy, the goals of the user have shifted, which means the resources in terms of documentation have also changed.
Documentation takes different forms and categories, depending on the target audience. These categories mainly include:
- Tutorials
- How-to guides
- Reference
- Explanation
Tutorials
A tutorial is an experience that takes place under the guidance of a tutor. A tutorial is always learning-oriented.
A tutorial is where the instructor holds the reader's hand and takes them through steps to achieve a predefined goal. They provide a sense of safety and comfort to the reader because they are in the instructor's hands.
How To Guides
How to guides are directions that guide the reader through a problem or towards a result. How-to guides are goal-oriented.
How-to guides are checklists. They assume that the reader already has some knowledge. The goal of the guide is to apply the steps to what the reader is working on or wants to achieve at the time.
Reference
Reference guides are technical descriptions of the machinery and how to operate it. Reference material is information-oriented.
A reference contains information in the form of facts; no action is needed.
Explanation
Explanation is a discusive treatment of a subject, that permits reflection. Explanation is understanding-oriented.
Explanations reveal information in the fold that can be read while in the bathroom or doing a mundane task.
To explore more of the different categories with examples and sample goals, check out this resource
Remember, documentation is not just a task; it's a powerful tool for informing and educating users. The essential categories will help you craft targeted, effective documents that meet your objectives and resonate with your audience. Adios!
Top comments (0)