Wiki Standards and Protocol

From AFSWiki
Jump to: navigation, search

Contents

Titles and sections

Page title capitalization

When you create a new wiki page, capitalize all important words in its title ("title case"). Prior to September, 2009, the official style guideline for AFS Wiki was not to capitalize important words in titles, so you will see many pages that break this guideline. Please don't create more of them.
Examples of correct capitalization:
Examples of incorrect capitalization:
  • Information for host families

Single vs plural titles for lists

If a page consists of a list, e.g., of local positions, then make the title plural, e.g. local positions and NOT local position.

Avoid special characters and punctuation in the title

Please remember the person at the search box, trying to locate your page. If they don't type it precisely the Wiki search function won't find it or may give several resulting pages where each word in the search request is found. It is not intuitive to guess what special character might be in your page title. Keep the title as short and simple as possible.
"Scholarship and Incentive Deadlines" is preferable to "Scholarship & Incentive Deadlines" in a title since it makes the URL easier to type, and the consistency saves people from having to guess whether we've used "&" or "and" this time. The same is true of quote marks. Avoid them in a title. In the body of the page, special characters are fine.
Additionally these characters are absolutely prohibited in the title or text as they are used by the Wiki system for syntax formatting and routing.
{ } [ ] < > | # : / \

Use section headings

Articles are not to be organized using, as an example, numerals or letters as is common with a alphanumeric outlines. Instead, use the mediawiki section headings

Avoid Time Sensitive Words, Dates or Times

Words like "New" or "Recently" "Coming Soon" are only new, recent or coming soon for a short period of time. This makes the page a candidate for deletion when it is no longer New. The Wiki was designed for slow changing articles and articles of historical value and not for Postit Note type articles. Include these comments with an expiration to them as a Special Paragraph with it's own "Section Heading" in a major subject article. This Section Heading can be given a direct referenced with an anchor (#) as you see here
http://www.afswiki.org/index.php/AFS_Wiki_style_guide#Use_section_headings
Use words like "New" or "Just Released" or "This Week/Month/Year" or "Revised" in the body of the page if necessary, but even then indicate a reference date. Poor style (with emphasis added):
The Alliance has distributed an Action Alert asking that we contact our Senators urging them to cosponsor legislation recently re-introduced by Sens. Tim Johnson (S-SD) and Norm Coleman (R-MN).
Better style:
In late 2007, the Alliance distributed an Action Alert asking that we contact our Senators urging them to cosponsor legislation re-introduced by Sens. Tim Johnson (S-SD) and Norm Coleman (R-MN).
An exception would be the title for minutes since this is intended as an historical document.

Avoid Using "AFS" in the Title

This whole Wiki is about AFS, so AFS in a title is usually redundant and will make your content more difficult to find through search.
Ignore this general guideline if you have a good reason.

Short page names

Don't use entire sentences for a page title - keep it simple. Instead of "We are please to announce that nominations for the Galatti award for 2010 are now being accepted", use "Galatti Award Nominations for 2010".

Generic page names

Make page names identifiable. Instead of "Agenda April 9" which doesn't mean anything, use "Orientation Workgroup Agenda April 9 2011".

Page categories

Put all pages into a category to make finding them easier, for example, all pages related to sending should include reference to Category:Sending.

Formatting

Use standard wiki formats

For standard MediaWiki formats, see: WikiMedia Help page.

Content

Keep the AFS Wiki DRY

Whenever you notice duplication of a concept or block of text, try to eliminate all but one of them, and convert the others to linked references. If no single wiki page seems worthy of "owning" the concept, then give the concept its own, dedicated page.

Linking

Link Generously

Links to other pages within the AFS Wiki help people find what they need. They also help keep the wiki DRY (see previous guideline) by reminding the author that it's better to link to other content than to duplicate it. To find pages to link to, use the search function.

Linking to other pages on this Wiki

  1. This is a good link to a page -> [[Form A]] (known as an internal link)
  2. This is a bad link to a page -> [[http://www.afswiki.org/index.php| Form_A]] (known as an external link)

Linking to Files

When a link to a file is required please link to a page that hosts the file and not directly to the file with a URL. If a file is ever updated on the Wiki it is stored in a different location unlike what you are familiar with on your desktop hard drive. The old document or media will be removed through our routine maintenance leaving a direct link as in # 2 below dead. a link as in # 1 will always be updated and will not go dead when the old file is removed. Also an external link as in 2 will make the Wiki think it is coming from outside of the Wiki and tell us that it is not being used on this Wiki. There are other security issues not explained here that make example 2 strictly prohibited.
  1. This is a good link to a file -> [[Media:2011 Form A Fill.pdf]] or [[Media:2011 Form A.pdf | 2011 Form A]]
  2. This is a bad link to a file -> [http://www.afswiki.org/w/uploads/d/d6/2011_Form_A_Fill.pdf]

Linking to Pages Outside of this Wiki

Keep in mind when linking to an external file or web page that web sites are under constant maintenance and redesign so this link could be broken at any time. The example 2 above under Linking to Files that is restricted is perfectly OK if you are linking to a page or file on another site like at afsusa.org

Test Your Links

Whether linking to a Wiki user name, another page or a file, test your link before saving the page. At the bottom of every page being edited are three buttons the middle of which is the Show preview button which allows you to see what the page will look like without actually saving the page. If during a preview you see any red text you will know that you have a bad link. This could be something as simple as the case being wrong on one letter or as complex as the wrong syntax.

Articles should be clearly structured

Relevant sections of an article should be grouped appropriately. Facts should be "findable", but do not need to be highlighted for the reader beyond what would be typical for grouping and/or structural purposes.

Gender-neutral language

Wikipedia has some guidelines for gender-neutral language which would also be appropriate for the AFS Wiki.

Unique data

Do not copy/paste information from other websites into the wiki. Instead, just provide a link to the external webpage.

Do not copy information that is in Global Link

The wiki is meant to store non-structured data, it is not a database. Therefore, information about volunteers, schools, etc. which is found in Global Link should not be replicated in the wiki.

Revisions and history

Use the 'Show preview' button

Editing a wiki page is quick and easy by design, but then making mistakes can also be as quick and easy. As a general rule, always preview changes by using the 'Show preview' button before clicking 'Save page.' This will prevent excess revisions from cluttering the history log.

Concisely capture change descriptions in the change summary

The history log of an article is a very useful tool which should be used to its fullest. The overall description of the changes made to an article should be concisely captured in the change summary. In some cases, for this summary to be concise, it might make sense to make multiple, successive edits to the article, grouped by change type.

Periodic deletion

Orphan pages

Except for pages which are linked to by being in a category, orphaned pages are not useful as they cannot be easily found and they are subject to periodic deletion.

News articles

While a history of news articles is useful for new volunteers or those who have not visited the wiki recently, they lose their relevance after a while. Therefore, the news article list will be truncated after a time (currently two years) and any pages which would thereby become orphaned if they are not referenced elsewhere will also be deleted.

Pages with expiring data

Pages which expire should have an expiration date noted inside the document and be linked to a category of expiring pages so they can be easily located.

Namespaces

User information belongs on the User page

Information pertaining to a specific user, such as a picture, biography, and contact information, and not pertaining to any actual AFS function, belongs on the user page. Example: User:TWinters.
The exception would be an information page for a special event such as a National Council Candidate however personal information such as phone number, email address etc should be reserved for the User page.

Avoid personal information outside of the User page

This guideline is the converse of the previous one. It makes it easy for anyone to update their contact information. More importantly, it preserves privacy, since according to the AFSWiki Access Policy, User pages can only be accessed by registered Wiki members, while most other pages can be accessed by anyone.
Personal tools