Wiki Style Manual

Tikiwiki Manual of Style

• Tikiwiki Manual of Style
  • Naming Conventions
    • General
    • Capitalization
    • Wiki Words
  • Grammar
    • No Jargon
    • Active Voice
  • Headings
    • Capitalization
    • Line Spacing
    • Page Titles
  • Headings
  • Emphasis
    • Bold
    • Examples
    • Italic
    • Source Code
  • Links
    • Wiki Page Names
    • External Links
  • Lists
    • Numbered Lists
    • Bulleted Lists
  • Graphics
  • Icons
  • Footnotes, Questions, Comments.

Naming Conventions

General

• As short as possible.
• Page names should contain action verbs that clearly describe what the end user wants to do. Use "Adjusting Stombergs" instead of "Stroms Adjust"
• Use keywords and be brief whenever possible. Dont say "about the features" when "features" will do. Imagine what will be typed in the search engine and use that.
• Avoid non-alphanumeric characters, except where appropriate (especially punctuation).

Capitalization

In Page Names: Capitalize all significant words. In Section/Heading Titles: Capitalize all significant words.

Wiki Words

A Wiki Word is simply two or more words smashed together with each word being capitalized, like this: WikiWord or AnotherWikiWord. A Wiki Word is one way to create a link to a new Wiki page. It will cause a link to a Wiki Page and if that page does not exist, it will allow you to create it. If you are making a page (like THIS Style page) and want to use the {maketoc} tag to create a table of contents that links to different sections on the SAME page based on headers, then NO NOT use Wiki words in your header titles. This is because the {maketoc} tag will not see it as a header on the current page, but instead it will think you want to link to a completely different Wiki page.

Grammar

No Jargon

Write in a straigh-forward manner, similar to how you might speak. Use complete words and avoid jargon. For example, use carburetor, transmission (or gearbox), and sparkplugs instead of carbs, tranny, and plugs.

Active Voice

Passive voice is great if you're writing a novel, but it can make technical information difficult to read. For example:

Headings

Use the exclamation mark at the beggining of a line to create headings. Do not use bold, centered text or anything else.

• ! for page titles
• !!major headings
• !!!minor headings

Capitalization

In titles, capitalize all nouns, pronouns, adjectives, verbs, adverbs, and first and last words. Don't capitalize articles (unless used as the first word), coordinate conjunctions, and prepositions. Do not add dots in titles as they are not sentences but labels. Separate the heading tag (!) from the first letter of the heading for easy double-click word select and fast visual source reading.

!Adding a new user

! Adding a New User

Line Spacing

Except for the page title, leave a blank line BEFORE a heading or subheading but don't leave a blank line AFTER.

! Adding a New User
!!Fill the form

Fill and click.

!!Check the perms
Go to admin panel.

! Adding a New User

!! Fill the Form
Fill and click.

!! Check Permissions
Go to admin panel.

Page Titles

At the top of the page, type ! followed by a decent title for the Wiki page you're editing. That can be different than the wiki pagename to provide more information, but only in some case, and generally a title identical to pagename is better.

Headings

Using Headings is strongly reccomended for all pages. Heading objects are useful for creating a {maketoc} tag, and for accessibility conformance too. Do not use other kinds of formatting (e.g. title bar, centered text, arbitrarily large fonts, colored fonts) to denote headings.

!Heading One - reserved for page titles. Normally not used in content. !!Heading Two - Subtitles / Sections within a page. May be accompanied with a horizontal rule. !!!Heading Three - (optional) equivalent to __bold__. Useful for long and complicated pages. Type !! followed by the major heading text __bold__ paragraph headings. (reccomended). For level three type headings that display inline with the paragraph. !!!!heading four - (avoid) - appears as plain text.

Emphasis

Bold

• Use bold sparingly.
• Use bold in table headings (recommended).
• Use bold to provide heading items in bulleted lists.
• Use bold to refer to important actions, safety items, etc.
• Use bold or all caps: not both. "With the mixture screw fully seated, turn the screw two full turns in an anti-clockwise direction."

Examples

If your article requires an example, use a text box and Example: in bold, like this:

You should consider where you live in deciding what color to paint your car.

Italic

Use Italic for indicating personal point of view, quoting, citation, or comments.

Source Code

Although it is unlikely you will need this is a wiki about British cars, pieces of code source, either html, smarty, php, javascript or any other require the use of CODE plugin for proper escaping and design. Try to separate code clearly from text content, on a separate line when possible, like if it was an illustration.

Links

Any text placed in double parenthesis will become a link to another wiki page. For example, if there is a wiki page called British Car History, and you wanted to link to it in your page, you would type ((British Car History)) If that page does not exist, it will put a "?" at the end like this: British Car History? You would then click the ? in order to create the new page.

Wiki Page Names

If you want to link to a page, but want to call the link something different than the wiki page name, just separate the actual page name from the displayed name using a | (pipe) character. For example, if you wanted to have a link called "return" that takes you back to the link discussed in the previous section (British Car History), you would do this: ((British Car History|Return)) This would appear as Return but it would take you back to British Car History page when clicked. It is recommended that you not use this method of hiding the wiki page name as it is much better and more intuative for all involved if all the links contain the actual wiki names. (However, I will confess that I have some Home links that take the reader back to the starting page in this wiki which is actually called "The British Car Forum Wiki".

External Links

Add relevant useful external links on a separate line. Don't put them in the body of a paragraph. Use a bulleted (*) list with a label on first line and one or many URLs beneath, one on each line; hide long lists using the list continuation code (+). For an example, see Blogs?. Never obfuscate an external URL with descriptive text.

• Wrong:
  

  For more information, see the 
  [http://www.computer.org/author/style/capitals.htm|IEEE Style Guide].

• Right:
  

  For more information, see the IEEE Style Guide, located at 
  [http://www.computer.org/author/style/capitals.htm].

• InterWiki Links To link to external Wiki pages at tikiwiki.org, use the tw: prefix.

Lists

Whenever possible, use bulleted (*) or numbered (#) lists. Do not number (or letter) lists by hand.

Numbered Lists

Always use a numbered list when you are describing a series of steps that must be followed in a certain sequence.

Bulleted Lists

Use bulleted (*) lists liberally!

Graphics

• Storage Use attached images rather than linking to the image gallery or other external sourceed images (although this can be done). To attach an image, use Upload Picture (an option that appears when you're editing a Wiki page).
• Filenames Name your picture with the name of the page, stripping spaces, indexed with the rank number in the page, like in MyWikiPage1?.jpg, MyWikiPage2?.jpg, etc .. for images in the page ((My Wiki Page))
• Tag Include images with the Wiki {img} tag (not the HTML tag).
• Border (optional) To help differentiate the graphic from surrounding text, place the graphic in a box (here's how: ^{img}^ ).
• Size Maximum width is 600 pixels, but smaller is better. Ideal is about 300 pixels wide.
• Format If the image is not an icon or similar in size please use .jpg only.
• Position Place images after the related text (not before).
• In-Text Reference Within the text, always refer to the image (for example, "The following illustration shows...").

Icons

• Only use icons in exceptional situation and always take in account that it maybe cannot be displayed for any reason, so marking a special content with icon should also be done with some formatting.
• { picture file=img/icons/cool.gif} is used to indicate a Tip, an hint or a special quote.
• { picture file=img/icons2/1.gif} is used to indicate a warning.

Footnotes, Questions, Comments.

• My footnotes are only visible to the user who edited them, therefore, it's only useful as your personal footnotes about the page. Do not use page content for asking a question or making a remark to collaborators! Use comments area instead. This will make the job of final text cleanup much easier.