Diff for "WikiConventions"

Not logged in - Log In / Register

Differences between revisions 4 and 5
Revision 4 as of 2009-08-11 21:04:56
Size: 1943
Editor: kfogel
Comment: Temper the advice to put a "Help" link in summary bars.
Revision 5 as of 2009-08-11 21:05:22
Size: 1919
Editor: kfogel
Comment: wording tweak
Deletions are marked like this. Additions are marked like this.
Line 11: Line 11:
When appropriate, the summary bar can end with a sentence encouraging the reader to ask for help if needed and linking to the [[Help]] page. This won't be right for every summary bar; just use your judgement. If the page is about performing some complex task, such as [[Getting]] or [[Running]], then it's more important to offer help than it would be for a merely informational page. When appropriate, the summary bar can end with a sentence encouraging the reader to ask for [[Help|help]] if needed. This won't be right for every summary bar; just use your judgement. If the page is about performing some complex task, such as [[Getting]] or [[Running]], then it's more important to offer help than it would be for a merely informational page.

This page tells you the conventions we use in maintaining this wiki. Please ask for help if you have any questions.

Most of the conventions in this wiki are self-explanatory. If you see something wrong, please just fix it (or if you're not sure, ask for help and then fix it).

Summary Bar

Most pages have a horizontal, black-background summary bar near the top, stating briefly what that page will tell the user. This is so readers can know quickly whether or not they've landed in the right place. (See Getting or Running, for example). A summary bar looks like this:

This page tells you how to frobnicate Launchpad's flux capacitors. Ask for help right away if you have any questions.

When appropriate, the summary bar can end with a sentence encouraging the reader to ask for help if needed. This won't be right for every summary bar; just use your judgement. If the page is about performing some complex task, such as Getting or Running, then it's more important to offer help than it would be for a merely informational page.

Please put a summary bar on any new pages you start. If you see existing pages that don't have the bar, fix them. (You can just copy-and-paste from one of the pages that does have it.)

Distinguish Between Explanatory Pages and Reference Pages

When a page explains a topic from the top down, don't try to pack too much information onto that page; instead, split material out to sub-pages as necessary. But when a page is a reference page, it's okay to make it big, because the expectation is that the reader will search within the page rather than browse it from the beginning.

WikiConventions (last edited 2010-04-27 00:15:29 by adiroiban)