• Vastliggende pagina
  • Info
  • Bijlages
Verschillen tussen versies 27 en 30 (omvat 3 versies)
Versie 27 sinds 2010-09-25 18:15:36
Grootte: 13351
Auteur: testcees
Commentaar:
Versie 30 sinds 2010-11-26 12:19:47
Grootte: 13570
Commentaar:
Verwijderingen worden op deze manier gemarkeerd. Toevoegingen worden op deze manier gemarkeerd.
Regel 2: Regel 2:

[[community/DocumentatieTeam| << Beginpagina documentatieteam]]
Regel 6: Regel 9:
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. 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.
Regel 11: Regel 14:
<<BR>>Dit werkt momenteel nog niet, het voorbeeldartikel is nog in aanmaak en staat voorlopig [[/Voorbeeldartikel|hier]]. <<BR>>Dit werkt momenteel nog niet, het voorbeeldartikel is nog in aanbouw en staat voorlopig [[/Voorbeeldartikel|hier]].
Regel 13: Regel 16:
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}}}. 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}}}.
Regel 15: Regel 18:
Lees in ieder geval ook deze richtlijnen vooraleer je begint te schrijven. Lees in ieder geval ook deze richtlijnen vooraleer u begint te schrijven.
Regel 19: Regel 22:
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]]. 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 [[http://wiki.ubuntu-nl.org/HelpOnMoinWikiSyntax|wiki-syntaxis]] (Engelstalig) en in de handleiding [[community/WerkenMetDeWiki|Werken met de wiki]].
Regel 21: Regel 24:
== 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.
== 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.
Regel 24: Regel 27:
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. 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]]. Voor het geval er al een gelijkaardig artikel bestaat kunt u beter het betreffende artikel verbeteren en aanvullen met uw informatie.
Regel 32: Regel 35:
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. 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.
Regel 34: Regel 37:
Artikelen die tot doel hebben om een beveilig te omzeilen zijn niet gewenst. Artikelen die tot doel hebben om een beveiliging te omzeilen zijn niet gewenst.
Regel 39: Regel 42:
 * 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.  * 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.
Regel 41: Regel 44:
 * Je begint je artikel met de titel. Kies een korte, duidelijke titel die de inhoud dekt.  * U begint uw artikel met de titel. Kies een korte, duidelijke titel die de inhoud dekt.
Regel 43: Regel 46:
 * 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>>  * 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); vermeldt bij LTS (Long Term Support) versies ook expliciet deze aanduiding.<<BR>>
Regel 45: Regel 48:
 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>>  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.<<BR>>
Regel 47: Regel 50:
 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.  U geeft bij voorkeur de werkwijze voor zo veel mogelijk varianten mee, zo bereikt uw artikel de meeste gebruikers. Toon uw uitleg dus zowel met schermafbeeldingen (zie verder) als met commando-opdrachten.
Regel 49: Regel 52:
 * Maak ook een inhoudstabel aan. Gebruik de [[/GeschiktVoorDocumentatie|GeschiktVoor]]-macro, die maakt automatisch een inhoudsopgave aan.  * Maak ook een inhoudstabel aan. Gebruik de [[/GeschiktVoorDocumentatie|GeschiktVoor]]-macro; die maakt automatisch een inhoudsopgave aan.
Regel 51: Regel 54:
 * 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.  * 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.
Regel 53: Regel 56:
 * 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>>  * 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.<<BR>>
Regel 55: Regel 58:
 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>>  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.<<BR>>
Regel 57: Regel 60:
 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.  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 controleren.
Regel 59: Regel 62:
 * Je eindigt je artikel met een korte slotbeschouwing. Vertel wat het eindresultaat zou moeten zijn en geef enkele praktische toepassingsmogelijkheden.  * U eindigt uw artikel met een korte slotbeschouwing. Vertel wat het eindresultaat zou moeten zijn en geef enkele praktische toepassingsmogelijkheden.
Regel 61: Regel 64:
 * 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.  * 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.
Regel 63: Regel 66:
 * 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]].  * 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. Je vindt een overzicht van alle categorieën en hun beschrijving op de [[./|hoofdpagina]].
Regel 67: Regel 70:
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. 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|taalgebruik]] in de documentatie; er staan ook enkele veelvoorkomende fouten opgesomd.
Regel 71: Regel 74:
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. 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 u de lezer veel gemakkelijker iets duidelijk maken. Ook zal informatie op die manier gemakkelijker blijven hangen.
Regel 73: Regel 76:
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. 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 je de afbeeldingen bijvoorbeeld op een USB-stick bewaart.
Regel 75: Regel 78:
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. 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.
Regel 87: Regel 90:
|| Bestandsnamen || ''Cursief'' || ''hardware.html'' || ||
Regel 93: Regel 97:
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. 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.
Regel 97: Regel 101:
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. Als u aan een artikel werkt, voeg dat dan toe aan de [[community/ArtikelenInAanbouw|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.
Regel 99: Regel 103:
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. 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 u aan het doen bent en geef een link naar uw artikel. Zo hebben forumleden, documentatie-schrijvers en het documentatieteam een plaats om ideeën voor uw artikel aan te brengen.
Regel 103: Regel 107:
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. 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 het forumtopic van zijn/haar artikel.
Regel 105: Regel 109:
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. Als u een klein foutje vindt in de officiële documentatie mag u dat rechtstreeks aanpassen. Indien u ingrijpender veranderingen wilt doorvoeren, maak een forumtopic aan, of reageer op een bestaand topic.
Regel 109: Regel 113:
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]]. 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 u gemakkelijk identificeren, zodat de samenwerking op de wiki gemakkelijker verloopt. Meer over werken met de wiki vind u in onze [[community/WerkenMetDeWiki|wiki-handleiding]].
Regel 112: Regel 116:
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. Door een rechtenprobleem kunt u 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 114: Regel 118:
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. 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 jezelf 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.
Regel 119: Regel 123:

[[community/DocumentatieTeam| << Beginpagina documentatieteam]]

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


Dit werkt momenteel nog niet, het voorbeeldartikel is nog in aanbouw en 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 vooraleer 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.

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 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); vermeldt 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 mee, 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; die maakt 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 controleren.

  • 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. Je 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 kun 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 je 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.

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 het beste per geval bekeken worden. Het is handig om te overleggen op het betreffende topic op het forum.

Laat je 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 tegelijk ook een nieuw 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, documentatie-schrijvers en het documentatieteam 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 het forumtopic van zijn/haar artikel.

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

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.

Door een rechtenprobleem kunt u 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 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 jezelf 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.

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.

<< Beginpagina documentatieteam

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