I'm creating this post based in The documentation system but since it is a long article I decided to create a summary with of it and a few more things. But I recommend you to read and study this article, it has more contents and specific cases with explanation and context for them.
Topics
A good documentation must have 4 main topics:
- Explanation: discursive explanation
- Reference: dry description
- Tutorial: a lesson
- How to Guide: a series of steps
credits: The documentation system
How we starting at Highsoft?
After picking a topic to write and document, the first thing to do is reference and explanation, which we did together. First we take a literal explanation of the term, and after that we explain how such a topic works in our system.
To create the tutorial, we took the topic in question and explained the procedure from end to end, in a simple, quick, basic and useful way
We must complement then with the how to guide, where we deal with more specific subjects and go deeper in the explanations
We added one more thread for possible warnings and the explanation of them. As we are an ERP, it is normal for us to trigger warnings on the screens to inform what is happening, and we have a topic to describe these warnings and point out possible problems that may occur.
Finally we have this:
Remember to always put yourself in the customer's shoes and try to understand the possible answers he needs:
- how to do this?
- what is it?
- what do i do when...?
- why did this happen?
If your documentation has the answer to these questions, you have a good documentation . If not, just add it!
Top comments (0)