Gentoo-en:Style Guide

From Gentoo-en
Jump to: navigation, search

Offical Documents TOC


Gentoo Wiki articles are primarily "howto" articles containing instructions on installing, configuring and using software and hardware.

Language Style

Articles should use plain English, avoiding use of technical terms where possible. Where technical terms are used, they should be defined (either directly or indirectly by linking to appropriate articles or pages).

Articles should be written from a third person point of view. That is, never refer to "I" or "me". Instead refer to the person reading the article as "you".

Page Style

Articles should be plain, using markup where appropriate. The purpose of the wiki is to provide instructions, not look beautiful. Images should not be used to decorate or stylize articles.

Format

Articles should contain the items listed here, in the order that they appear.

  • Begin with a summary of the article subject.
  • Detail what the article will achieve and any prerequisites (software or knowledge). You might also want to mention inter-related topics that the article does not cover and where to find information on those topics.
  • Guide the user through the process step-by-step, explaining what commands do, especially where it may not be obvious.
  • Provide a section on troubleshooting if appropriate - this section may contain common problems or errors encountered and how to fix them.
  • List any related articles, even if they have been linked within the article itself. This list can include articles from other sites.
  • Make sure you use the appropriate templates

Hardware Articles

Hardware articles should provide the following extra information:

  • Where appropriate, the output of "lspci -nn" or "lsusb" related to the device.
  • Alternate names by which the device is known. This does not include listing all devices (eg. laptops, wireless devices) in which the hardware (eg. sound card, wireless chipset) can be found.

Discussion

Discussion of any kind should appear on the articles discussion page, not in the article itself.

Headings

Headings use the standard Mediawiki convention and start at == (not =).

Categories

Categories ([[Category:Foo]]) should be at the end of articles. All articles should be in at least 1 category.