Gentoo Wiki:Guidelines

From Gentoo Wiki
Jump to: navigation, search
Important
This page is still very much a work in progress. Please come back and check this page regularly. And feel free to discuss these guidelines and propose new ones on the Discussion page.

Avoid first person

As the wiki is a community effort, and the content pages are informational, there should be no mention of "I" or "we". Articles should be written in third person, as reported fact.

The user can be addressed as "you" where appropriate, but third person and passive voice are preferred, as they sound more professional and objective.

Best practices for new articles

  • The title should be specific, short and unambiguous. Don't use ALLCAPS unless necessary.
  • Start with a short introductory paragraph, without any heading. (Especially headings such as Introduction or Overview are discouraged.)
  • Divide your article into logical sections. Each main section should have a level 2 heading (as level 1 is used for the page title). A Table of Contents will be automatically generated from the headings. As with titles, headings should be short and specific, and only use needed capitalization.
  • There should be one empty line above headings, and no empty line below. The first paragraph (or list item, ...) should start immediately on the next line.
  • Keep paragraphs short (generally 1-5 sentences), as that makes the article easier to read.
  • Link to other articles in the wiki where appropriate.
  • Add the article to one or more categories. Categories should be stated at the bottom, or at the very top of the page without any empty line below them.
  • Use Templates where appropriate.

Lists of links

  • Add links to other resources available on *.gentoo.org under a See also heading at the end of the article.
  • Put links to non-gentoo.org resources under an External resources heading at the end of the article.