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.

  • Schermafdrukken

    • worden geplaatst door gebruik te maken van het label “figure”.
    • gebruik altijd alt-teksten en een afbeeldingsbeschrijving. Die zullen genummerd worden in de PDF-export, wat hen onderscheidt van de teksten.
    • worden meestal geplaatst boven een lijst als ze deel zijn van stap voor stap-instructies.
    • zouden zo weinig mogelijk instructies moeten bevatten over de stappen die er voor moeten genomen worden. Bij voorkeur enkel de stapnummers, zodat ze gemakkelijk uitgewisseld en vertaald kunnen worden vermits de tekst dan geen deel is van de afbeelding. Dat kan ook betekenen dat de vertalers de stappen kunnen vertalen en niet onmiddellijk de afbeeldingen moeten vervangen.
    • zijn gemaakt met Shutter in Ubuntu. Het is gemakkelijk om de tekstballonnetjes toe te voegen die de verschillende stappen aanduiden. Natuurlijk kan er gelijk welke schermafdruksoftware gebruikt worden. Bij voorkeur zien de tekstballonnetjes er hetzelfde uit voor consistentie. De gebruikte kleur is #4C711D.
    • hebben tekstballonnetjes die refereren naar de stappen die genomen moeten worden en die onder de figuur uitgelegd worden.
    • zou enkel de nodige zone mogen tonen en niet het hele scherm, de URL, knoppenbalken en dergelijke.

  • 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 *).

  • Kleine knopjes kunnen in de tekst gezet worden, zoal edit, manage. Zij worden toegevoegd door vervanging. Alle vervangingen worden bijgehouden in het bestand shortcuts.rstext dat toegevoegd wordt aan het begin van elk bestand waarin een vervanging gebruikt wordt. Ze worden in de tekst gerefereerd als Bewerk-knop edit om bijvoorbeeld aan te tonen wat de actie is die er er kan mee doen.

  • Er moet een indexverwijzing gemaakt worden voor elke sectie.

  • Nieuwe functies krijgen een ook index in de vorm “single: Nieuw in Mahara 1.5; [de nieuwe funchtie]”.

  • 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.