[Mageia-bugsquad] Making the triage guide easier to read

Marja van Waes marja11 at xs4all.nl
Fri Sep 30 16:35:27 CEST 2011


Hi everyone,

Andre999 gave me some good tips on how to make our Triage Guide easier 
to read, without changing the content:

****************************************************************************

After "OK, it is a duplicate, what should be done?"
(One could say "OK, it is a duplicate, what next?")
----
"Since the bug is a duplicate of a previous report, you should set the 
status of the bug to
<code>RESOLVED DUPLICATE</code>
with the appropriate bug number.
This will usually be the only action required.
If the fact that the bug is a duplicate ..."
----

- Any text that is to entered by the user should be between 
<code>...</code>.
This will make it appear on a separate line, and always monospaced (so 
as to be very readable), even if the other text is proportional.
(This is also used for computer code, hence the name.)

- Frequently starting a new sentence on a new line makes it easier to 
follow a somewhat complex line of thought.
- Using bullets a little more consistently should help as well.
- Point form is much clearer than amorphous paragraphs.

But as I said above, the content seems very well thought out, it is only 
the presentation that could use a little enhancement.

Don't forget: documenting is more an art than a science, so don't be 
afraid to use a little imagination in your presentation.  And practice a 
lot.

BTW, in programming we learn what is called "prettyprint" in English.  
Basically the above principles, for internal documentation of program code.
(Judging by external documentation, you can see that some programmers 
learn a little better than others.:) )

************************************************************************************************************

The code tags don't need to be converted, in the new wiki they are the 
same as in the old one. If no one opposes, I'd like to start replacing 
the "strong" tags for words like "RESOLVED INVALID" "NEEDINFO" etc. with 
code tags.

Regards,
Marja





More information about the Mageia-bugsquad mailing list