<< Beginpagina documentatieteam

Documentatierichtlijnen

Op deze pagina vindt u een aantal richtlijnen die u kunnen helpen bij het schrijven van documentatie voor Ubuntu. Probeer tijdens het schrijven deze richtlijnen goed in gedachten te houden. Op die manier kunt u een helder artikel schrijven dat Ubuntu-gebruikers met plezier zullen lezen.

Voorbeeldartikel

Het voorbeeldartikel staat voorlopig hier.

Het gemakkelijkste is om u te baseren op het voorbeeldartikel; dat is een kant en klaar artikel waar u enkel de inhoud nog moet aanpassen. Het heeft reeds de juiste opmaak en indeling en bevat enkele voorbeelden omtrent het gebruik van afbeeldingen, tabellen en dergelijke. Om het voorbeeldartikel in te laden kiest u bij het aanmaken van een nieuwe pagina in de linkerkolom voor ArticleTemplate.

Lees in ieder geval ook deze richtlijnen voordat u begint te schrijven.

Wiki-syntaxis

U zult veel te maken krijgen met verschillende opmaakmethoden die de wiki-software biedt; het is handig als u de basis-syntaxis onder de knie krijgt. Wanneer u een pagina bewerkt wordt er onderaan een kort schema getoond dat de belangrijkste syntaxis bevat. Meer informatie is te vinden op de helppagina over wiki-syntaxis (Engelstalig) en in de handleiding Werken met de wiki.

Onderwerp van uw artikel

Het is van groot belang dat u een goed onderwerp kiest voor uw artikel. Zorg ervoor dat het onderwerp niet te breed is: het artikel "Gnome configureren" bijvoorbeeld, zal al snel te groot worden. In plaats daarvan kunt u misschien beter beginnen met een artikel over het installeren van een nieuwe printer onder Gnome.

Vergeet ook niet te controleren of er al vergelijkbare artikelen bestaan: kijk daarvoor in de wiki-documentatie, maar ook in de artikelen in aanbouw. Voor het geval er al een gelijkaardig artikel bestaat kunt u beter het betreffende artikel verbeteren en aanvullen met uw informatie.

De artikelen moeten in lijn zijn met de gedragscode. De artikelen moedigen het gebruik van vrije software aan en gaan bij voorkeur uit van software uit de officiële Ubuntu-pakketbronnen.

De in het artikel beschreven procedure is bewezen correct. Risico's bij het uitvoeren van de in het artikel beschreven procedure zijn minimaal en indien anders wordt dit duidelijk vermeld. Denk hierbij aan risico's op dataverlies maar ook aan afwijkende pakketbronnen of mogelijke wijzigingen die conflicteren met een Ubuntu-upgrade.

Artikelen die tot doel hebben om een beveiliging te omzeilen zijn niet gewenst.

Indeling

Het is belangrijk dat lezers in één oogopslag hun informatie kunnen vinden; om die reden moet elk artikel een eenduidige indeling vertonen. Denk bijvoorbeeld aan een inhoudsopgave, een indicatie voor de geschikte versie van Ubuntu en een referentielijst. Een overzicht:

• Bovenaan uw pagina komt een kader dat aanduidt dat dit artikel nog in aanbouw is en dus mogelijk fouten bevat. Er komt ook een link naar het forumtopic voor dit artikel (zie verder). Indien uw pagina een kopie is van de officiële documentatie (zie verder), verwijs dan naar dat artikel. Dit kader wordt door het documentatieteam verwijderd als uw artikel wordt overgeplaatst naar de officiële documentatie.
• U begint uw artikel met de titel. Kies een korte, duidelijke titel die de inhoud dekt.

• Onmiddellijk na de titel volgt een overzicht voor welke varianten en versies van Ubuntu uw artikel geschikt is. Zoals u weet zijn er van Ubuntu verschillende officiële afsplitsingen (bijvoorbeeld Kubuntu, Xubuntu en Edubuntu, maar ook Ubuntu Server), verder aangeduid met de term varianten. Elke zes maanden komt er ook een nieuwe versie van het systeem uit (bijvoorbeeld 8.04 LTS of 8.10); vermeld bij LTS (Long Term Support) versies ook expliciet deze aanduiding.
  

  Indien het verschil in werkwijze tussen de verschillende varianten klein is, kunt u er het beste één algemeen artikel van maken. U geeft dan in de tekst de verschillende werkwijzen aan voor elke variant. Als uw onderwerp specifiek over één variant handelt of indien de verschillen groot zijn, kunt u beter aparte artikelen maken.
  U geeft bij voorkeur de werkwijze voor zo veel mogelijk varianten aan; zo bereikt uw artikel de meeste gebruikers. Toon uw uitleg dus zowel met schermafbeeldingen (zie verder) als met commando-opdrachten.

• Maak ook een inhoudstabel aan. Gebruik de GeschiktVoor-macro of <<TableOfContents(3)>>; deze maken automatisch een inhoudsopgave aan.

• Schrijf een inleiding waarin u vertelt waar het artikel over gaat. Geef indicaties waarom mensen het artikel zouden lezen en de stappen uitproberen, en wat het doel en het eindresultaat is. Geef ook aan of enige voorkennis vereist is, met links naar andere artikelen waar mogelijk. Waarschuw voor mogelijk onvoorziene consequenties.

• Na de inleiding komt het eigenlijke artikel. Vertel in duidelijke stappen wat men dient uit te voeren, maar leg ook uit wat er daadwerkelijk gebeurt. Het volstaat bijvoorbeeld niet om te stellen dat een bepaald programma geïnstalleerd moet worden; zeg ook waarom dat noodzakelijk is, wat het precies doet en wat de functie is in deze context.
  

  Vermeld ook links naar andere artikelen: verwijs in voorgaand voorbeeld naar de pagina over hoe men software kan installeren. Zo wordt dubbele informatie vermeden en vindt de lezer toch meer informatie als hij die nodig heeft.
  Verwijs tenslotte in de tekst naar de referentielijst (zie verder). Als u informatie van een externe website overgenomen of vertaald hebt, geef dat dan ook aan bij het betreffende stuk. Dat is in veel gevallen noodzakelijk m.b.t. auteursrecht en het laat anderen toe om eventuele foutjes gemakkelijker te corrigeren.

• U eindigt uw artikel met een korte slotbeschouwing. Vertel wat het eindresultaat zou moeten zijn en geef enkele praktische toepassingsmogelijkheden.
• Onderaan uw artikel komt de (liefst alfabetische) referentielijst. Maak hier een overzicht van de bronnen die u raadpleegde bij het schrijven van uw artikel; dat kunnen forumtopics zijn, websites, pagina's uit de Engelstalige documentatie, Wikipedia enz. Hier kunnen mensen desgewenst meer informatie over het onderwerp vinden. Geef een auteur, een titel en een link naar de bron. Vermeld ook de taal als die verschillend is van het Nederlands.

• Het laatste element van uw pagina is de categorie waartoe ze behoort; door het artikel in de juiste categorie te plaatsen kan het eenvoudiger teruggevonden worden. U vindt een overzicht van alle categorieën en hun beschrijving op de hoofdpagina.

Taalgebruik

Gebruik de correcte Nederlandse spelling en grammatica; schrijf uw artikel in Standaardnederlands, zo kunnen alle Nederlandstaligen de tekst goed begrijpen. Spreek de lezer aan met de beleefdheidsvorm "u", maar overdrijf niet met formaliteit. Lees zeker de pagina omtrent taalgebruik in de documentatie; er staan ook enkele veelvoorkomende fouten opgesomd.

Voorbeelden en schermafbeeldingen

Het geven van voorbeelden (bij voorkeur aan de hand van schermafbeeldingen) is een goede manier om de gebruiker te begeleiden bij het lezen van het artikel. Op die manier kunt u de lezer veel gemakkelijker iets duidelijk maken. Ook zal informatie op die manier gemakkelijker blijven hangen.

Gebruik het standaardthema van uw Ubuntu-variant wanneer u schermafbeeldingen gaat maken. Zo ziet onze documentatie er eenvormig uit en krijgt de gebruiker niet de indruk dat hij mogelijk verkeerd bezig is. U kunt hiervoor eventueel gebruikmaken van een gastsessie, waarbij u de afbeeldingen bijvoorbeeld op een USB-stick bewaart.

Schermafbeeldingen maakt u met de toets PrintScreen (PrtSc). In de overgrote meerderheid van de gevallen is enkel het actieve venster interessant: gebruik hiervoor de combinatie Alt+PrintScreen. (Door een bug kan het voorkomen dat het vensterkader niet mee wordt opgenomen in de afbeelding; schakel hiervoor tijdelijk de grafische effecten uit als je schermafbeeldingen maakt). Probeer aandacht te besteden aan de focus in het venster, leg die (met de tab-toets) op het element waarmee de gebruiker het venster succesvol kan sluiten. De afbeeldingen kunt u uploaden naar uw artikel met de link Bijlage; verkies steeds deze mogelijkheid boven een externe opslagplaats.

Typografie

Om de documentatie er uniform uit te laten zien, is het noodzakelijk om in bepaalde situaties dezelfde typografie te gebruiken. Hier volgt een tabel van die situaties en welke typografie daarvoor de richtlijn is. Ook worden er twee voorbeelden gegeven die het wat duidelijker maken.

Instructies voor verschillende versies:

• Ubuntu 8.04 LTS en 8.10: instructies

• Ubuntu 9.04 en 9.10: instructies

Probeer in principe voor de rest het standaard-lettertype te gebruiken. Soms kan het echter overzichtelijk zijn om een stuk tekst cursief of vet te maken. Dit kan het beste per geval bekeken worden. Het is handig om te overleggen op het betreffende topic op het forum.

Laat uw artikel zien

Als u aan een artikel werkt, voeg dat dan toe aan de artikelen in aanbouw. Op die manier kunnen andere documentatie-schrijvers tips aanleveren, fouten verbeteren of meehelpen aan het artikel. Ook kan het documentatieteam de status van uw artikel bekijken, en wanneer het klaar is integreren in de hoofddocumentatie. Ook als het artikel geplaatst is, kunt u nog gewoon aanpassingen doen.

Maak eventueel een forum topic aan op het documentatie-onderdeel van het forum. Vertel kort wat u aan het doen bent en geef een link naar uw artikel. Zo hebben forumleden een plaats om ideeën voor uw artikel aan te brengen.

Bestaande artikelen aanpassen

Het is vanzelfsprekend de bedoeling dat alle artikelen (nieuwe, maar ook bestaande) aan deze richtlijnen voldoen. Het staat u vrij om aanpassingen te doen aan alle artikelen in aanbouw, wellicht is het interessant om met de auteur te overleggen via irc of een forumtopic over het artikel.

Een klein foutje in de officiële documentatie mag u rechtstreeks aanpassen. Indien u ingrijpender veranderingen wilt doorvoeren, maak dan een forumtopic aan of reageer op een bestaand topic.

U kan contact opnemen met het documentatieteam via IRC op het Freenode netwerk in het kanaal #ubuntu-nl-team

Gebruikersaccount

Om met de wiki te kunnen werken is het noodzakelijk een account aan te maken. Op die manier kunnen anderen u gemakkelijk identificeren, zodat de samenwerking op de wiki gemakkelijker verloopt. Meer over werken met de wiki vind u in onze wiki-handleiding.

Als u vaker op de wiki werkt, is het een goed idee een eigen gebruikerspagina aan te maken. Op uw gebruikerspagina kun je wat informatie over uzelf plaatsen, maar ook plaatst u hier contactinformatie (bijvoorbeeld een e-mailadres of uw forumnaam). Op die manier kunnen andere schrijvers gemakkelijk contact met u opnemen, mocht dat nodig zijn. Een gebruikerspagina aanmaken is heel gemakkelijk. Klik eerst op uw gebruikersnaam, rechtsboven in het scherm (naast Settings en Uitloggen). Klik daarna op Bewerken (Tekst) linksboven in.

<< Beginpagina documentatieteam