Difference between revisions of "Wiki Guidelines"

From Cube Wiki
Jump to: navigation, search
 
(No difference)

Latest revision as of 16:59, 12 December 2014

Wiki Guidelines

From Aardappel's post on the forum:

Do not be afraid to re-factor things. So far it seems people just add to the wiki, and leave what is there in place. One of the ideas behind a wiki is that it's easy to reorganize the soup of data. If you add something that makes the structure of the document less than ideal, do not be afraid to restructure other people's text into a different set of pages and links. Do not be afraid to even delete other people's text, once you conclude it has become redundant. The original structure was just me making some example pages, it may not be ideal for the current content anymore.

Feel free to post to this page's discussion board if you have major changes in mind, or certain conventions.

Don't let pages grow to huge amounts of text, wikis are best when they are small sections of text per page, but heavily linked.

In that same way, one of the goals of the wiki is to function as a FAQ, so if we get the thousandth post on the "your server did not reply to ping" message we can point people to exactly one wiki page that has all the firewall tutorials you could ever wish for.

Some stuff on the wiki is straight out of the main documentation. Duplication is not good: it means if I update the main documentation the wiki instantly contains outdated information. Since the wiki is more for FAQs and tutorials, and the docs more for hardcore factual reference, it is good to have each section of the wiki refer to pages in the docs where the exact command reference related to the topic can be found.

If you know of topics that have been discussed on this forum before, it is really helpful to find these threads, and make a wiki page out of the most explanatory posts. In fact, maybe I should be typing this post in the wiki rather than on the forum, it is getting rather long...

If additional people want editing access, apply for it at the bottom of this wiki page.

Formatting

To ensure readability, editors of this wiki should follow the basic rules outlined here.

Italics

  • Directory paths and file names should be //``italicized``//.
  • Large block quotes should be in //italics//. If possible, link to the original source.

Code

  • Code/script listings but also one-liners in a reference should be formatted as {{``Code``}}.
  • In-text code like variables should be in {{``Code``}}.
  • Sauerbraten shell output should be formatted in {{``Code``}}.
  • Code should be without quotes or a slash, so instead of "/getmap", getmap would be appropriate.

Other

  • Create page names properly. They are the page title, and should be written like one. For example: multiplayer+guide should be written as a proper title: Multiplayer Guide.
  • Use headings properly, in large blocks of text, these help with the [[toc]] tag. The page name is the title, write a short introduction if need be, then use the first level heading =Like So=. Then subheadings, ==Two== and ===Three===.
  • Try to keep spacing through the article consistent with the layout for easy reading when, for instances where people are skimming.
  • Do not use horizontal lines to separate text, use headings.
  • Use the **``bold``**``** and __``__``underlined``____ stuff only to highlight extremely important information.
  • Dashes should be shown as two hyphens: -- not — (em dash), – (en dash), or - (hyphen).
  • Spelling and grammar should be kept to AmE (American English) or BrE (British English) when possible.
  • Quotes should be straight -- not curved or "smart".
  • Ellipses should be the three simple dots: ... without spaces or a fourth dot.
  • Ctrl+C is the Windows and Linux key style for key commands, but on a Mac, the equivalent combination should be written Command-C.
  • Windows should be referred to as Windows, not Win32 or Windoze. Mac OS X should be Mac OS X (or OS X), not MacOS or OSX. Linux is tricky.

Special Considerations

FAQ Page

Unlike the other pages on the wiki, the Frequently Asked Questions page is intended to be a quick stop for commonly asked questions with quick simple answers. If you need more than one or two paragraphs to explain an answer, consider using a separate page and linking to it from the FAQ. This keeps the page concise, and reduces the loading time for the page regulars, especially useful if they don't want to read a large block of text.