2. Informatie voor Mahara documentatieschrijvers

Deze lijst evolueert terwijl ik werk aan de documentatie. Er zijn vele zaken waarvoor ik afspraken maak. Ik wil ze op een centrale plaats bewaren, zodat anderen er toegang toe hebben en ik er kan naar verwijzen ;-)

Deze lijst staat niet in een bepaalde volgorde.

  • Screenshots are placed as figures and always include alt text and a figure description. The latter will receive numbering in the PDF export.

  • Gebruikte verwijzingen zijn:

    • opmerking: voor alles dat wat meer aandacht nodig heeft
    • waarschuwing: voor alles dat voorzichting gedaan moet worden
    • zie ook: voor referenties naar andere documenten als ze speciale aandacht nodig hebben. Referenties naar andere documenten kunnen ook in de tekst opgenomen worden.
    • takenlijst: voor het bijhouden van een takenlijst

  • Knoppen zoals * Bewaar* of Kopieer pagina en ook portfoliosecties zoals Inhoud; Portfolio enz worden benadrukt als vette tekst (met een enkele *).

  • Little buttons can be included in the text.

  • Screenshots of Mahara sections are not made inline, but receive the “figure” directive. They always have an alt tag and also a brief description which will show up below the image and is numbered in LaTeX PDF.

  • Screenshots should have as little instructions as possible about the steps that are to be taken in them. Preferably, only the step numbers so that they can be exchanged more easily and the text of the steps is translatable because it is text and not part of the image. That could also mean that translators can translate the steps but don’t immediately have to change the screenshot.

  • Inline images that are refered to in the textsuch as edit should be included as shortcuts with the reference at the bottom of the page.

  • Er moet een indexverwijzing gemaakt worden voor elke sectie.

  • Lange secties moeten verdeeld worden over meerdere pagina’s om het bewerken meer beheersbaar te maken.

  • reStructuredText heeft geen hiërarchische set voor hoofding. Ze hangen af van de individuele bestanden. Om consistent te zijn, bestaat volgende afspraak:

    • Hoofding 1, vb. 1.: ===============
    • Hoofding 2, vb. 1.1.: —————
    • Hoofding 3, vb. 1.1.1.: ~~~~~~~~~~~~~~~
    • Hoofding 4, vb. 1.1.1.1.: ^^^^^^^^^^^^^^^

  • Hoofdingen kleiner dan h4 moeten vermeden worden.

  • I create screenshots with Shutter in Ubuntu. It is easy to add the callouts which indicate the steps to take. However, any other screenshot software can be used. Preferably, the callouts look similarly. The color is #4C711D.

  • The callouts in the screenshots refer to the steps that need to be taken.

  • Screenshots should only show the necessary area and not the entire screen or URL address bars etc. where not necessary.