Formatting Guidelines

On this site, we have a few formatting guidelines that we request be followed when editing or creating new pages.

Location
The page location matters. Why would you put a page called "ISR Routines" under the "Home" tab? Things related to developing or documentation go under the "Documentation" tab, and things related to the project as a whole go under the "Home" tab. It would also be nice if you include a link to your page somewhere, be it inline or part of a table of contents.

Formatting General
This is how pages should be formatted.
  • Avoid from using image headers, borders, or decorative elements.
  • Format your pages in wiki markup and not HTML.
  • This is a technical project, walls of text are fine. That being said, we like them to be fairly short, or broken up with lists, charts, or graphs.
  • Use inline links to point to relevant pages where applicable.

Formatting Specific
  • At the very top of each page, include the pages name as a Heading 1, with the page description the line directly underneath.
    • If there is no appropriate description, it may be left out.
    • If the page is part of a series, make the description italic and point to the series TOC.
  • Pages should be divided into sections, headed by a bold line containing the name of that section. Continue to put the section content directly underneath that line.
    • Sections should be divided by one line break.
  • Use lists properly
  • Use links properly

Voice
  • Try to aim for dry, witty humor.
  • Spell everything correctly. Most modern web browsers have a spell check feature built in.
  • Use proper grammar.
  • In places where it is required to be strict, be sure to not seem menacing.
  • Think Cave Johnson and Aperture.
  • Be friendly, outgoing, and energetic.

If you seem to be having troubles with any of this, contact someone who can help you, or check out the source of a properly formatted wiki page.

Last edited Oct 15, 2012 at 11:44 PM by joshbeitler, version 2

Comments

No comments yet.