Documentatierichtlijnen

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

Voorbeeldartikel

Het gemakkelijkste is om je te baseren op het voorbeeldartikel, dat is een kant en klaar artikel waar je 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 kies je bij het aanmaken van een nieuwe pagina in de linkerkolom voor ArticleTemplate.

Lees in ieder geval ook deze richtlijnen vooraleer je begint te schrijven.

Wiki-syntaxis

Je zult veel te maken krijgen met verschillende opmaakmethoden die de wiki-software biedt, het is handig dat je de basis-syntaxis onder de knie krijgt. Wanneer je 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 je artikel

Het is van groot belang dat je een goed onderwerp kiest voor je artikel. Zorg ervoor dat het onderwerp niet te breed is: het artikel "Gnome configureren" bijvoorbeeld, zal al snel te groot worden. In plaats daarvan kun je 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. In het geval er al een gelijkaardig artikel bestaat kun je het betreffende artikel beter verbeteren en aanvullen met jouw informatie.

Een beperkt aantal onderwerpen wordt onderhouden door het Ubuntu-documentatieteam. Het betreft de artikelen:

• Standaard installatiehandleidingen van de ondersteunde Ubuntu-versies (Ubuntu, Kubuntu, Xubuntu, Edubuntu en de serverversie).
• Standaard (multimedia) toevoegingen na een installatie.

De artikelen moeten in lijn zijn met de Ubuntu-filosofie en 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 worden anders duidelijk vermeld. Denk hierbij aan risico's op dataverlies maar ook aan afwijkende pakketbronnen of mogelijk wijzigingen die conflicteren met een Ubuntu-upgrade.

Artikelen die tot doel hebben om een beveilig 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 je pagina komt een kader die 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 je pagina een kopie is van de officiële documentatie (zie verder), verwijs dan naar dat artikel. Dit kader wordt door het documentatieteam verwijderd als je artikel wordt overgeplaatst naar de officiële documentatie.
• Je begint je 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 je artikel geschikt is. Zoals je 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 maak je best één algemeen artikel. Je geeft dan in de tekst de verschillende werkwijzen aan voor elke variant. Als je onderwerp specifiek over één variant handelt of indien de verschillen groot zijn maak je liefst aparte artikelen.
  Je geeft bij voorkeur de werkwijze voor zo veel mogelijk varianten mee, zo bereikt je artikel de meeste gebruikers. Toon je uitleg dus zowel met schermafbeeldingen (zie verder) als met commando-opdrachten.

• Maak ook een inhoudstabel aan. Gebruik de GeschiktVoor-macro, die maakt automatisch een inhoudsopgave aan.

• Schrijf een inleiding waarin je vertelt waar het artikel over gaat. Geef indicaties waarom mensen het artikel zouden lezen en de stappen uitproberen, 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 moet geïnstalleerd worden; zeg ook waarom dat noodzakelijk is, wat het precies doet en wat zijn functie is in deze context.
  

  Leg ook links met 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/zij die nodig heeft.
  Verwijs tenslotte in de tekst naar de referentielijst (zie verder). Als je informatie van een externe website overgenomen of vertaald hebt geef dat dan ook aan bij het betreffende stuk. Dat is in vele gevallen noodzakelijk m.b.t. auteursrecht en het laat anderen toe om eventuele foutjes gemakkelijker te controleren.

• Je eindigt je artikel met een korte slotbeschouwing. Vertel wat het eindresultaat zou moeten zijn en geef enkele praktische toepassingsmogelijkheden.
• Onderaan je artikel komt de (liefst alfabetische) referentielijst. Maak hier een overzicht van de bronnen die je raadpleegde bij het schrijven van je 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 je pagina is de categorie waartoe ze behoort; door het artikel in de juiste categorie te plaatsen kan het eenvoudiger teruggevonden worden. Je vindt een overzicht van alle categorieën en hun beschrijving op de hoofdpagina.

Taalgebruik

Gebruik de correcte Nederlandse spelling en grammatica; schrijf je 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 kun je de lezer veel gemakkelijker iets duidelijk maken. Ook zal informatie op die manier gemakkelijker blijven hangen.

Gebruik het standaardthema van je Ubuntuvariant wanneer je schermafbeeldingen gaat maken. Zo ziet onze documentatie er eenvormig uit en krijgt de gebruiker niet de indruk dat deze mogelijk verkeerd bezig is. Je kan hiervoor eventueel gebruikmaken van een gastsessie, waarbij je de afbeeldingen bijvoorbeeld op een USB-stick bewaart.

Schermafbeeldingen maak je 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 kan je uploaden naar je 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 dan het beste per geval bekeken worden. Het is dan handig om te overleggen op het betreffende topic op het forum.

Laat je artikel zien

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

Maak tegelijk ook een nieuw topic aan op het documentatie-onderdeel van het forum. Vertel kort wat je aan het doen bent en geef een link naar je artikel. Zo hebben forumleden, documentatieschrijvers en het documentatieteam een plaats om ideeën voor je 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 je vrij om aanpassingen te doen aan alle artikelen in aanbouw, wellicht is het interessant om met de auteur te overleggen via het forumtopic van zijn/haar artikel.

Als je een klein foutje vindt in de officiële documentatie mag je dat rechtstreeks aanpassen. Indien je ingrijpendere veranderingen wil doen reageer op, of maak, een forumtopic aan.

Gebruikersaccount

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

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

Licentie

Alle teksten en bijlagen die toegevoegd worden op onze wiki vallen automatisch onder de CC-BY-SA licentie. Voeg enkel tekst en bijlagen toe die beschikbaar zijn onder een compatibele licentie (en voldoe daar ook aan; verwijs bijvoorbeeld naar de bron in de referentielijst), of waarvan je zelf de auteur bent.