• Vastliggende pagina
  • Info
  • Bijlages
Verschillen tussen versies 26 en 28 (omvat 2 versies)
Versie 26 sinds 2010-06-07 20:59:48
Grootte: 3906
Auteur: vistaus
Commentaar:
Versie 28 sinds 2010-10-03 19:09:15
Grootte: 13411
Commentaar: Een kleine toevoeging i.v.m. bestanden
Verwijderingen worden op deze manier gemarkeerd. Toevoegingen worden op deze manier gemarkeerd.
Regel 2: Regel 2:
= Documentatie-richtlijnen = = Documentatierichtlijnen =

||<tablestyle="float: right;"><<TableOfContents(2)>>||

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 ==
Regel 4: Regel 11:
<<BR>>Er wordt gewerkt aan een nieuwe versie van dit artikel. De nieuwe versie staat [[http://wiki.ubuntu-nl.org/community/RichtlijnenVoorstel/|hier]]. <<BR>>Dit werkt momenteel nog niet, het voorbeeldartikel is nog in aanmaak en staat voorlopig [[/Voorbeeldartikel|hier]].
Regel 6: Regel 13:
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}}}.
Regel 7: Regel 15:
'''Op deze pagina vind u een aantal richtlijnen die u kunnen helpen bij het schrijven van documentatie voor {K|X}Ubuntu. Probeer tijdens het schrijven deze richtlijnen goed in uw achterhoofd te houden. Op die manier kunt u een helder artikel schrijven dat Ubuntu-gebruikers met plezier zullen lezen.''' Lees in ieder geval ook deze richtlijnen vooraleer je begint te schrijven.
Regel 9: Regel 17:
== 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.
== Wiki-syntaxis ==
Regel 12: Regel 19:
Vergeet ook niet te controleren of er al vergelijkbare artikelen bestaan. In dat geval kunt u het betreffende artikel misschien verbeteren en aanvullen met uw informatie. 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 [[http://wiki.ubuntu-nl.org/HelpOnMoinWikiSyntax|wiki-syntaxis]] (Engelstalig) en in de handleiding [[community/WerkenMetDeWiki|Werken met de wiki]].
Regel 14: Regel 21:
== Voorbeelden en screenshots ==
Het geven van voorbeelden (bij voorkeur aan de hand van screenshots) 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.
== 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.
Regel 17: Regel 24:
Maak screenshots bij voorkeur met het standaard Ubuntu thema ingeschakeld. Als u Kubuntu of Xubuntu gebruikt, kiest u voor het standaardthema van deze varianten. Onder Gnome kunt u met Alt+Print``Screen gemakkelijk een screenshot van een enkel venster maken, zodat u niet handmatig aan het snijden hoeft. Vergeet ook niet te controleren of er al vergelijkbare artikelen bestaan: kijk daarvoor in de [[./|wiki-documentatie]], maar ook in de [[community/ArtikelenInAanbouw|artikelen in aanbouw]]. In het geval er al een gelijkaardig artikel bestaat kun je het betreffende artikel beter verbeteren en aanvullen met jouw informatie.
Regel 19: Regel 26:
'''Ubuntu 9.10 en ouder:''' "Human"-thema {{{#!wiki note
Op dit moment is het alleen mogelijk nieuwe pagina's te maken in het /community-gedeelte.<<BR>>Noem een nieuw artikel http://www.wiki.ubuntu-nl.org/community/ArtikelNaam. Het is de bedoeling dit binnenkort te verruimen.
}}}
Regel 21: Regel 30:
'''Ubuntu 10.04:''' "Ambiance"-thema De artikelen moeten in lijn zijn met de [[http://www.ubuntu-nl.org/ubuntu/filosofie|Ubuntu-filosofie]] en [[http://www.ubuntu-nl.org/ubuntunl/gedragscode|gedragscode]]. De artikelen moedigen het gebruik van vrije software aan en gaan bij voorkeur uit van software uit de officiële Ubuntu-pakketbronnen.
Regel 23: Regel 32:
'''Kubuntu 8.10 en 9.04:''' "Oxygen"-thema, 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.
Regel 25: Regel 34:
'''Kubuntu 9.10 en 10.04:''' ''Vensters:'' Oxygen-thema ''Plasma:''Air-thema. Artikelen die tot doel hebben om een beveilig te omzeilen zijn niet gewenst.
Regel 27: Regel 36:
== Spelling en grammatica ==
Probeer tijdens het schrijven zoveel mogelijk correcte Nederlandse spelling te gebruiken, en bouw uw zinnen logisch en correct op. Op die manier zullen lezers niet afhaken omdat ze door lange, ingewikkelde zinnen moeten ploegen.
== 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:
Regel 30: Regel 39:
Als u moeite heeft met spelling en grammatica, zullen andere schrijvers proberen uw artikel te controleren en te verbeteren. Eventueel kunt u op het [[http://forum.ubuntu-nl.org/documentatie|forum]] vragen of iemand dit voor u wil doen.  * 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.
Regel 32: Regel 41:
== Laat uw artikel zien ==
Als u aan een artikel werkt, plaats dan een link naar het artikel op de [[community/ArtikelenInAanbouw|Artikelen in aanbouw]]-pagina. Op die manier kunnen andere documentatieschrijvers 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 is overgeplaatst, kunt u nog gewoon aanpassingen doen.
 * Je begint je artikel met de titel. Kies een korte, duidelijke titel die de inhoud dekt.
Regel 35: Regel 43:
Om comfortabel te werken op de wiki, is het aan te raden een [[http://wiki.ubuntu-nl.org/community/Richtlijnen?action=newaccount|account aan te maken]]. Op die manier kunnen anderen u gemakkelijk identificeren, zodat de samenwerking op de wiki gemakkelijker verloopt. Meer informatie over werken met de wiki vind u in onze [[community/WerkenMetDeWiki|Wiki-handleiding]].  * 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.<<BR>>
Regel 37: Regel 45:
== Maak een gebruikerspagina aan ==  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.<<BR>>

 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 [[/GeschiktVoorDocumentatie|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.<<BR>>

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

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

|| '''Situatie''' || '''Richtlijn''' || '''Voorbeeld 1''' || '''Voorbeeld 2''' ||'''Eventuele opmerkingen''' ||
|| Knoppen || '''Vet''' || '''Toepassen''' || '''OK''' || ||
|| Knoppen in een menu || '''Vet → Vet''' || '''Bestand → Openen...''' || '''Systeem → Beheer → Synaptic Pakketbeheer''' || ||
|| Knoppen in een tekstgebaseerd menu || '''Vet''' || '''Ubuntu uitproberen zonder te installeren''' || '''<Ja>''' || ||
|| Programmanamen || ''Cursief'' || ''Firefox webbrowser '' || '' Synaptic Pakketbeheer '' || ||
|| Pakketten || ''Cursief'' || ''myspell-nl'' || ''ubuntu-restricted-extras'' || ||
|| Bestandsnamen || ''Cursief'' || ''hardware.html'' || ||
|| Toetsenbordknoppen || Standaard || Enter || Alt-F2 || Toetsencombinaties met een streepje ||

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 [[community/ArtikelenInAanbouw|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 [[http://forum.ubuntu-nl.org/documentatie/?action=post|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 [[http://wiki.ubuntu-nl.org/community/Richtlijnen?action=newaccount|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 [[community/WerkenMetDeWiki|wiki-handleiding]].
Regel 39: Regel 113:
<<BR>>Op dit moment helaas niet mogelijk. Door een rechtenprobleem kan je momenteel geen gebruikerspagina aanmaken. Dit zou binnenkort verholpen moeten worden.<<BR>>Neem tot die tijd contact op het het documentatieteam voor het maken van een gebruikerspagina.
Regel 41: Regel 115:
Als u vaker op de wiki werkt, is het een goed idee een eigen ''gebruikerspagina'' aan te maken. Op uw gebruikerspagina kunt u wat informatie over uzelf plaatsen, maar ook plaatst u hier contactinformatie (bijvoorbeeld een e-mailadres). Op die manier kunnen andere schrijvers gemakkelijk contact met u opnemen, als dat nodig is. 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.
Regel 43: Regel 117:
Een gebruikerspagina aanmaken is heel gemakkelijk. Klik eerst op uw 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 [[http://creativecommons.org/licenses/by-sa/3.0/deed.nl|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.

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


Dit werkt momenteel nog niet, het voorbeeldartikel is nog in aanmaak en staat voorlopig hier.

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.

Op dit moment is het alleen mogelijk nieuwe pagina's te maken in het /community-gedeelte.
Noem een nieuw artikel http://www.wiki.ubuntu-nl.org/community/ArtikelNaam. Het is de bedoeling dit binnenkort te verruimen.

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.

Situatie

Richtlijn

Voorbeeld 1

Voorbeeld 2

Eventuele opmerkingen

Knoppen

Vet

Toepassen

OK

Knoppen in een menu

Vet → Vet

Bestand → Openen...

Systeem → Beheer → Synaptic Pakketbeheer

Knoppen in een tekstgebaseerd menu

Vet

Ubuntu uitproberen zonder te installeren

<Ja>

Programmanamen

Cursief

Firefox webbrowser

Synaptic Pakketbeheer

Pakketten

Cursief

myspell-nl

ubuntu-restricted-extras

Bestandsnamen

Cursief

hardware.html

Toetsenbordknoppen

Standaard

Enter

Alt-F2

Toetsencombinaties met een streepje

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.

Door een rechtenprobleem kan je momenteel geen gebruikerspagina aanmaken. Dit zou binnenkort verholpen moeten worden.
Neem tot die tijd contact op het het documentatieteam voor het maken van een gebruikerspagina.

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.

community/Richtlijnen (laatst bewerkt op 2012-06-17 12:01:05 door rachidbm)