Help:Stijlgids

(Doorverwezen vanaf OpenSUSE Style Guide)
Ga naar: navigatie, zoeken
Richtlijnen voor inhoud
Hieronder staat eerste een kopie van de Engelse versie en daaronder staat de oude Nederlandse versie. Wij zijn bezig om deze in elkaar te schuiven. De vertalers.
Dit artikel is nog maar gedeeltelijk vertaald. Als u mee wilt helpen met vertalen lees dan Wiki vertalen naar het Nederlands.
The Style guidelines cover essentials on how to create or edit articles to ensure a consistent look and feel throughout. They are based on similar Wikipedia guidelines. The following guidelines include detailed information on styling openSUSE wiki articles.

General usability

Neutral style

Use a neutral writing style. Avoid the use of personal pronoun "I", "We", etc.

Keep it short and concise

When writing, consider how quickly you decide to read on, or not. Poorly written and overly wordy articles will not be read.

  • Do not add irrelevant or redundant content. People will read short, clear articles that give the information they need. But they will flee those bloated with irrelevant content.
  • Use a consistent, non-cluttered format from top to bottom. No one will read a lengthy article broken into sections by miss-matched layouts or colors. Those just make reading slower and serve to drive away the reader.
  • To make your article useful and popular, keep it short and concise!

See Article development on Wikipedia.

Structure

Title

  • Title should be clear and short. See Help:Examples of bad article title
  • Do not use cryptic Acronyms, unless sure they are widely know by the target audience.
  • Do not use CamelCase. Instead, use spaces.
  • Use the same capitalization style as Wikipedia.
  • Do not use a colon as separator in titles as it is used to designate a namespace in MediaWiki.
  • Avoid the use of special characters. Use [aA-zZ][0-9] characters only.

Section title

  • All above title guidelines apply to section titles also.
  • Since section titles form the table of contents a short telegraphic style aids readability and page navigation.
  • Do not repeat article title in the first section. Redundancy does not encourage further reading.
  • Do not use About or Introduction as name of the first section. First section of any article is introduction in a topic, so telling that explicitly doesn't bring anything new to the reader.

Headings

  • Use the = markup to create a heading. This way, the table of contents is automatically generated from the headings and that helps readers to go directly to the section of interest.
  • Start with double equal sign == not a single =.
Icon-forbidden.pngVerboden single equal sign (=) produces the same text size as the article title, which is not used in any common writing style.
  • Do not put links in headings. Instead, link the word or phrase the first time it appears in the section.
  • Split very long section into few subsections using subheadings.
  • Use ---- markup to create a horizontal separator before any level 2 heading (==), as this helps in smooth reading of the article
Example:
 ==heading 1==
 ===subheading 1.1===
 ===subheading 1.2===
 
 ----
 ==heading 2==
 ===subheading 2.2===
 ====subheading 2.2.1====
 =====subheading 2.2.1.1=====

 ----
 ==heading 3==

Content

openSUSE spelling

  • openSUSE is the only correct way to spell openSUSE. "OpenSUSE", "openSuSE", OpenSuse" and other variations are all wrongly formatted. As MediaWiki software cannot handle lower-case wiki page title, use Template:Lowercase_title when writing a wiki page whose title begins with "openSUSE".
  • Do not use trademark characters (such as © or ®) as this impedes the article reading.
  • Note that the spelling "SuSE Linux" and "SUSE Linux" are deprecated. Unless referring explicitly to an older release of openSUSE (10.1 and earlier release) for historical purposes, SUSE Linux Enterprise Server (SLES) or SUSE Linux Enterprise Desktop (SLED), use "openSUSE".

Duplication

Do not duplicate effort.

  • Check the openSUSE list of HOWTO's. There is already a large collection of articles. If one exist that covers the subject that you wish to write about then take time to read it and see if it can be improved.
  • The openSUSE forum has a collection of HOWTOs in the Advanced How To/FAQ (read only), forum and another less mature sub-forum Unreviewed How To and FAQ which may present a foundation you can build on.
  • There is also a large collection of HOWTO articles on The Linux Documentation Project.

Acronyms and abbreviations

  • When introducing new acronyms in an article, use the full name on its first occurrence followed by the abbreviated form inside round brackets. For example: Section titles automatically form the table of contents (TOC).
  • Avoid complex abbreviations as they make articles more difficult to read.
  • Always use standard and widely understood abbreviations as innovation may lead to wrong interpretation

Variables

Sometimes, a command input is specific to the user's system, such as system devices or username. Following conventions are to be used:

  • <username>, for example in path command /home/<username>
  • sdX for devices

Please note that:

  • Using such convention usually will require a note like: "Substitute the actual device/username (sda, sdb, hda, etc) in the place of sdX".
  • If multiple devices are discussed use the convention sdX, sdY, sdZ. If more than three devices need to be addressed. just begin with device sdN where is N is the last N letters of the alphabet.

New user safety

Warning: Be especially careful giving instructions that have to be run with root user privileges. Commands like dd, rm, fdisk, can do a lot of damage if used without understanding. New users often don't understand, but just copy and paste command:

  • Do not use example code which if copied and pasted directly into a command line interface will result in a disaster. For example, this command:
# dd if=openSUSE-11.2-KDE4-LiveCD-i686.iso of=/dev/sda

if copied directly to command line will overwrite user first hard disk. The /dev/sda is first hard disk and it exists in every computer, whereas this command: 

# dd if=openSUSE-11.2-KDE4-LiveCD-i686.iso of=/dev/sdX

is safe since it is highly unlikely that /dev/sdX exists and therefore an error will be returned (rather than overwriting sda).

Images

Placement

See Image markup for recommendations on the best markup to use. For ideas and examples of how to place images, see Picture tutorial.

Format

  • Drawings, icons and other such images (basically those with large, simple, and continuous blocks of color) should be in PNG format.
  • Photos should be in JPEG format.
  • Animations should be in animated GIF format.
Please note that old versions of articles do not show corresponding old versions of images, but the latest ones, unless the file names of the images have changed.

Colors

If you colorize something see Help:Colors for color tables with the standard openSUSE distribution and website colors.

Comments

  • Do not clutter article text with editorial comments/questions. Instead, use the article's discussion page.
  • If you want to communicate with other editors, make comments invisible to the ordinary article reader by using comment tags.
 <!-- This is an invisible comment.  -->

Wanted pages

To indicate that there is a need for some article that doesn't yet exist, create a link to the needed article in the text of an existing article. If there are at least two links to the same nonexistent article, it will be listed on Wanted Pages, which is a source of inspiration for many new wiki authors. While not everything there is really needed, common sense and your expertise will tell you which to choose from the list.

Elements

When writing, ensure to use the following convention.

Wiki markup

While it is possible to use HTML tags to format a page, using the MediaWiki markup will make source text easier to read and edit. You may also look at the Wiki reference card and the source code of a few articles.

Command keys

F5 and Tab

  • Code: <code>Button to press</code>
  • Description: Keyboard button to press.
  • Where: Anywhere

Command path

/usr/src/linux and /etc/SuSE-release

  • Code: <tt>/path/to/directory/or/file</tt>
  • Description: Directory path and file path description.
  • Where: Anywhere

Command input

$ user command
# root command
  • Code: <div class="shell">$ user command</div> or <div class="shell"># root command</div>
  • Description: Command to enter.
  • Where: Anywhere

Command output

output text
  • Code: (blank space)short output text or <pre>long output text</pre>
  • Description: Describe the result of an entered command.
  • Where: Anywhere

Meeting transcripts

... Content ...
  • Code: <div class="minutes"> ... Content ... </div>
  • Description: Display of meeting transcripts.
  • Where: Anywhere

Tables

Heading 1 Heading 2 Heading 3 Heading 4 Heading 5 Heading 6
Highlighted text Highlighted text Highlighted text Text Text Highlighted text
Text Text Text Text Text Highlighted text
Text Text Text Text Text Highlighted text
  • Code: See page source.
  • Description: Display a table with optionally highlighted text.
  • Where: Anywhere

Templates

See Template Guidelines.

See also

External links

Wij verzoeken u vriendelijk bij het maken en wijzigen van artikelen in de Wiki zich te houden aan de onderstaande richtlijnen. Kijk bij twijfel in het artikel Wikipedia-gids (Engels). Wij zullen proberen hier de basisdingen weer te geven en het verschil met de Wikipedia. Alle suggesties over hoe deze gids te verbeteren zijn zeer welkom. Gebruik de "Discussion"-link bovenaan voor het commentaar.


Titel van artikelen

De naam van uw artikel is ook de kopregel. Maak deze helder en kort en gebruik gewone taal:

  • Vermijdt, waar mogelijk, het gebruik van cryptische afkortingen, speciaal wanneer er een synoniem beschikbaar is met een vergelijkbare lengte.
  • maak, vooral in het Nederlands, spaarzaam gebruik van hoofdletters en gebruik spaties (in titels) want Mediawiki software kan daar prima mee omgaan en dat maakt het ook beter leesbaar. Vergelijk VoordelenVanOpenOffice vs. "Voordelen van OpenOffice" of "Voordelen van open office". Met die hoofdletters is het onmogelijk om aan te geven of het onderwerp gaat over de OpenOffice serie programma's of over offices die openheid voor iedereen nastreven.
  • Vermijdt het gebruik van de titel nog eens in de kop van de eerste paragraaf. Niemand heeft iets aan twee aaneengesloten regels die hetzelfde vertellen, zoals:
Voordelen van OpenOffice
Voordelen van OpenOffice
  • Een soortgelijke fout is het herhalen van de titel in "Over" of "Introductie". Uit het volgende voorbeeld blijkt dat dit niet veel verschilt van gewoon herhalen:
Voordelen van OpenOffice
Introductie tot voordelen van OpenOffice
  • Gebruik in de Engelse titels title-style capitalization [1]. In het Nederlands is dat niet gebruikelijk; niet doen dus.
  • gebruik bij het vertalen van artikelen exact dezelfde titel als de Engelse versie. Verwijs altijd naar de Engelse titel en zet de Nederlandse titel na het rechte streepje binnen de dubbele rechte haken. [[English Title|Nederlandse titel]] . Na het aanmaken van het vertaalde artikel met de Engelse titel kan met Move de Nederlandse titel aangebracht worden; maak deze gelijk aan de Nederlandse titel in de verwijzing. Markeer de Engelse pagina als Watch. Dat maakt het gemakkelijk om wijzigingen in deze pagina's bij te houden door op de Engelse wiki in te loggen en dan op Volglijst te klikken. U krijgt dan een lijst met alle pagina's die recent gewijzigd zijn en daarbij gemarkeerd welke door u sinds de wijziging niet zijn bezocht. Dat is een aanwijzing om de overeenkomstige Nederlandse pagina bij te werken.
  • vermijd een dubbelepunt als scheidingsteken in de titel. Zie Dubbelepunt in de titel.

Titel van een sectie

  • Deze kunnen langer zijn dan de titel van een artikel, maar denk wel aan de layout van de TOC (Inhoudsopgave). Deze wordt automatisch gegenereerd uit de kopjes waarbij een erg lange regel gevolgd door een korte niet erg helpt bij het lezen. Kies de titel van de sectie, indien mogelijk, een titel die rekening houdt met een nette layout van de inhoudsopgave.
  • Het gebruik van hoofdletters is hetzelfde als bij de titels van de artikelen. Het eerste woord van de titel is een hoofdletter en verder alleen hoofdletters als de Nederlandse taalregels dat voorschrijven. Vaak worden hoofdletters gebruikt om iets specifieks aan te duiden. "Voordelen van Open Office" betekent iets ander dan "Voordelen van open office". In het eerste geval is het de naam "Open Office" (bedrijf, tijdschrift of vereniging) in het tweede geval is het een algemene term over een kantoor dat open is (structuur of toegang). Door alleen hoofdletters te gebruiken gaat dat onderscheid mogelijk verloren.

Kopjes

  • Gebruik de = (kop) markering en niet de ''' (bold) markering om een kop te maken. Op deze manier wordt de inhoudsopgave automatisch gegenereerd vanuit de koppen, dat helpt de lezer om direct naar de interessante sectie te gaan.
  • Start met een dubbel is-teken == niet met een enkele =.
Let op: een enkel is-teken produceert dezelfde tekstgrootte als de titel van het artikel en dat is geen gebruikelijke schrijfstijl.
Voorbeeld:
 ==kop 1==
 ===onderkop 1.1===
 ===onderkop 1.2===
 ==kop 2==
 ===onderkop 2.2===
 ====onderkop 2.2.1====
 =====onderkop 2.2.1.1=====
  • Bij een lange tekst van een sectie is het beter deze verder onder te verdelen met ondertitels.
  • In Engelse tekst gebruikt u title-style capitalization voor de koppen in het Nederlands niet.

Gebruik Mediawiki opmaak

Hoewel het mogelijk is HTML-opmaak te gebruiken, maakt het gebruik van MediaWiki opmaak uw tekst gemakkelijker leesbaar en gemakkelijker te wijzigen.

Kijk eens op MediaWiki editing help (Engels) om te vernemen welke opmaakhulpmiddelen er zijn. U kunt ook naar de broncode van een paar artikelen kijken en vergeet niet de nieuwe mogelijkheden beschreven in Skin Management.

Voorbeelden: Bestandsnamen en shell-commando's
  • Als een bestandsnaam onderdeel van de tekst is gebruik dan fixed font, broncode:
<tt>fixed font</tt>
  • Voor een lange lijst kunt u gepaard <pre> en </pre> gebruiken.

Commentaar

Gebruik de discussie-pagina van een artikel voor uw commentaar. Vervuil de tekst van het artikel niet.

Als u wilt communiceren met andere editors dan kunt commentaar onzichtbaar maken voor de gewone lezer van het artikel. U moet de tekst die alleen bestemd is voor andere editors tussen deze tags <!-- --> zetten.

Voorbeeld: 

 hello <!--This is a comment.--> world

wordt weergegeven als:

hello world

Werk in uitvoering

De openSUSE wiki is een werk in uitvoering. Commentaar "Under construction", "niet klaar" etc. in deze context, zou zelden gebruikt moeten worden en alleen in het geval dat het belangrijk is aan de lezer te laten weten dat dit nog niet alle informatie is. Voor die gelegenheid is er het sjabloon Expand

Icon-expand.png Dit artikel is slechts een begin!
Dit artikel dient uitgebreid te worden. U bent van harte welkom om te helpen met de stijl richtlijnen.
. Dit sjabloon geeft een uniforme layout over de gehele wiki en geeft een lijst van artikelen in Category:Pages_that_need_expanding die door de vrijwilligers gebruikt wordt bij het zoeken van uit te voeren werk. Het is de bedoeling om de uitbreiding in de Engelse versie te doen.

In de Nederlandse versie van de wiki is er vertaalwerk te doen waarvoor het sjabloon {{Vertalen}} is gemaakt en de rubriek Te vertalen. Dit gaat meestal om pagina's die gedeeltelijk vertaald zijn. Als er voor een pagina alleen verwijzing is naar de Engelse pagina en u wilt deze graag vertaald hebben dan kunt u het sjabloon Vertalen op die pagina aanbrengen. Hopelijk is er dan iemand die de vertaling doet.

Syntax: 

        {{Expand}}
        {{Vertalen}}

Sjablonen

Kijk op de lijst met sjablonen voor enkele veel gezochte sjablonen.

Voor de lezer is het meestal niet zinvol om koppen en tabellen te zien die verder leeg zijn, maar soms is het te accepteren als het bedoeld is als sjabloon voor verdere bewerking.

Artikelgrootte

De manier om in een wiki te suggereren dat iemand een artikel zou moeten maken is door een koppeling te maken naar zo'n nog niet bestaand artikel in een bestaande tekst. Als er tenminste twee koppelingen zijn naar hetzelfde niet bestaande artikel dan verschijnt deze op Gewenste pagina's. Niet alles is werkelijk gewenst, maar gezond verstand en uw deskundigheid vertellen u wat uit deze lijst te kiezen. Hetzelfde geldt voor willekeurig geblaat met irrelevante inhoud. Als u een populair artikel wilt maken maak het dan kort en men zal dat meer lezen vanwege de gewenste informatie. Kijk op Artikel maken (Engels) op Wikipedia.

Koppelingen versus kopiëren van inhoud

Er zijn twee manieren om de inhoud van andere artikelen in te voegen:

  • Maak een koppeling naar een webpagina die relevant is in uw tekst. Het is minder werk en u hoeft geen aandacht te besteden aan het bijwerken. Het is altijd bij de tijd, maar dat kan uw artikel ook benadelen als:
    • het externe artikel naar een andere URL (dode koppeling) verhuisd of
    • de inhoud zodanig wijzigt dat het niet meer de juiste verwijzing is die het eens was.
  • Kopieer de relevante inhoud uit het externe artikel. Als u dit gebruikt om er zeker van de te zijn dat de inhoud niet wijzigt, verzeker u er dan van dat u de inhoud mag kopiëren (Copyright).

Overgenomen van "https://nl.opensuse.org/index.php?title=Help:Stijlgids&oldid=9077"