Small ideas about How to document very well

[zeroheure]

I'm sharing random ideas about documentation, that I'm thinking about for a while.

Here's a sample of a very well done documentation. IMHO, it is simple and straight:

It's an extract from a tutorial book on Scribus. The purpose of the extract is to create a template for a company's document. Text says:

When Scribus start, a windom opens to setup the document, it ask you to set its size and orientation (1) and its internal asymmetrical margins (2); 20 millimeters on left and right, 10 on top and 5 bottom. Note that if the four fields are chained, entering 20 mm in one of them will automaticaly apply this value to the three others. To change that, broke up the chain with a mouse-click on it.

This document has one page only, there is no need to change other parameters (3).

What is good

• user is supposed to understand, no verbosity
• only important things
• it is very visual,
  • the red color is the better to focus user's attention
  • numbers shows the zone, not a field, the text explain the fields
  • the picture even show the chain tip that is explained in the text
• not explained advanced features are shown
• it spoke to user, with a bit of familiarity (french readers could confirm ?)

Let's compare with the current sample doc for the fictional Partner Fax module:

• it is very verbose while we need only the picture and the first sentence. The Usage part is totaly obvious.
• a big red number on the picture would be better, while not mandatory. The doc would say This module adds a fax field into the partner form (1).
• it miss advanced informations about the module limitations that a customer could ask, like "where can I found the fax number format?, "can I type anything in it?", and so on. I would add You can type anything here, if you need more control, change the module code.

---

As a technical user, when I read computers docs it is often verbose and boring, like bug reports (and this post!). As we all knows, users never read docs and never report bugs, they only complains about things not working as expected. But I remember two past bug reports from Linus Torvald: the first one on Gnome file manager was sarcastic, the second one on a KDE feature was humorous ("make my wife happy"). Of course Linus is known to be direct but this kind of emotional things help to read and to memorize. One can add fun or at least nice things in documentation, like beautiful big red numbers.

Current modules documentation are also written by programmers well aware of the problem it solve, but sometimes hard to understand for others and thus hard to discover, which is the most important.

[yajo]

It seems you just nailed it about why we need this repo ❤️

[francesco-ooops]

Let's compare with the current sample doc for the fictional Partner Fax module:

Hi @zeroheure , could you link it for clarity?

[zeroheure]

@francesco-ooops Here it is https://oca-docs.netlify.app/module/partner_fax/