History: Tiki Manual of Style

            {REMARKSBOX(type="warning" title="suggestion")}This page should be ((moved)) to the Community site and become a general Manual of style for all Tiki sites, with possible sub sections for site-specific aspects.{REMARKSBOX}



!Tiki Manual of Style
Aka documentation guidelines

!!The Imperatives
The following rules are very important.
* Do not use HTML.
* Do not hide URLs - the documentation will be available in printed form as well as online.
* Use the ((Documentation Templates))!
* All pages must link to relevant ((Keywords)). 
* Use page ((alias)) instead of ((PluginRedirect))


__discuss this page__ at ((talk:Manual of Style))

!!Naming Conventions

!!!General
* Use Tiki, instead of Tikiwiki or TikiWiki (also see No WikiWords below)
* As short as possible.
* Page names should contain action verbs that clearly describe what the end user wants to do.  Use "Configuring Blogs" instead of "Blog Config" 
* Use Keywords whenever possible. Don't say "about the features" when "features" will do. Imagine what will be typed in the search engine and use that. 
* Use the terms and menu options that appear in the end-user version of the software. 
* Avoid non-alphanumeric characters. (especially punctuation)

!!!Capitalization
__In Page Names:__ Capitalize all significant words. 
__In Section/Heading Titles:__ Capitalize all significant words.

!!! No WikiWords
Whether you're naming a new page or referring to one, don't use WikiWords (CamelCase). To link to a Wiki page, spell and capitalize the page name correctly and enclose the name within double parentheses.
example, ~np~ ((Wiki Style)) ~/np~).

!!! No Jargon
Since this is targeted to Grade 8 English, use complete words and avoid jargon. Use  Administer, Configure, Development instead of Admin, Config, and dev.  

!! Headings
Use the exclamation mark, followed by a space at the beginning of a line to create headings. Using Headings is strongly recommended 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.  
*! 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.
{FANCYTABLE()}
__Wrong__ |{CODE()}!Adding a new user{CODE}
__Right__ |{CODE()}! Adding a New User{CODE}
{FANCYTABLE}

!!! Line Spacing
Except for the page title, leave a blank line BEFORE a heading or subheading but don't leave a blank line AFTER.
{FANCYTABLE()}
__Wrong__ |{CODE()}! Adding a New User
!!Fill the form

Fill and click.

!!Check the perms
Go to admin panel.{CODE}
__Right__ | {CODE()}! Adding a New User

!! Fill the Form
Fill and click.

!! Check Permissions
Go to admin panel.{CODE}
{FANCYTABLE}

!!!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 cases, and generally a title identical to pagename is better.
^__Proposed Alternative:__ Do not repeat Page Title. 
Reasons: 
*Plain language page name (see above) makes restating the page title redundant. 
*Pagename should (and can) be displayed by CMS rather than repeated in content. 
*If page is renamed, content doesn't necessarily have to change. 
(learned this the hard way)^

!! Emphasis

!!!Bold
Except for headings, use bold very sparingly. 
Use bold in table headings (recommended). 
use bold to provide heading items in bulleted lists (like those in this page). 
Use bold to refer to actions, buttons, text that appears on-screen, or the name of a configuration option. 
Use bold or all caps: not both.
^Example: "In ((Blog)), click __Use WYSIWYG Editor__ to edit your post in an easy-to-use, "what-you-see-is-what-you-get" formatting window."^

!!!Examples
Use the formatting above, with a text box and __Example:__ in bold.

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

!!!Source Code
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
Remember, the documentation will be printed. Don't hide Wiki page links or URLs!

!!!Wiki Page Names
Don't hide page names with label text. Wrong: "Read the ~np~ ((Tiki Manual of Style))
|rules)) ~/np~!" Right: Read the rules, which you'll find in ~np~ ((Tiki Manual of Style)) ~/np~.

!!!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 ((Blog)).
Never obfuscate an external URL with descriptive text. 

** __Wrong:__ 
++ {CODE()}For more information, see the 
[http://www.computer.org/author/style/capitals.htm|IEEE Style Guide].{CODE} 
** __Right:__ 
++ {CODE()}For more information, see the IEEE Style Guide, located at 
[http://www.computer.org/author/style/capitals.htm].{CODE} 
* __InterWiki Links__ To link to external Wiki pages at tikiwiki.org, use the tw: prefix. Below is the list of external wikis that we have defined in http://doc.tiki.org:

^::{img src="img/wiki_up/external_wikis_02.png" }::^

!! 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 image gallery. To attach an image, use __Upload Picture__ (an option that appears when you're editing a Wiki page). 
^Possible Alternative: Use of the image gallery may be preferred because 
*graphics may be used in more than one place
*graphics should be tracked and catalogued to speed updates when features change
^
* __Filenames__ Name your picture with the name of the page, stripping spaces, indexed with the rank number in the page, like in WikiUser1.png, WikiUser2.png, etc .. for images in the page ((Using Wiki Pages))
* __Tag__ Include images with the Wiki ~np~{img}~/np tag (not the HTML tag).
* __Border__ To help differentiate the graphic from surrounding text, place the graphic in a box (here's how: ~np~^{img}^~/np~).
* __Size__ Maximum width is 600 pixels.
* __Format __ GIF is forbidden. True color (16 or 24 bit) PNG doesn't offer good compression on large image sizes. 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, "In the following illustration, note...").

!!Plugins
Avoid using ((plugins)) unless they are necessary, or it is a page about the plugin.

!! Icons
* Only use icons in exceptional situations.  Formatting should stand on its own as we must assume that icons may not display in all contexts.  
* {icon name=thumbs-o-up} ~np~{~/np~icon name=thumbs-o-up} is used to indicate a Tip, an hint or a special quote.
* {icon name=warning} ~np~{~/np~icon name=warning} 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.

* When you transfer pages from tikiwiki.org, add a link to the doc page to the moved page, and add a link to the old page in the doc page. This will help housecleaning, too.
* Always indicate the inter-wiki link to the related tikiwiki.org pages.


!Alias
*(alias(Formatting Standards))
*(alias(Style Manual))
*(alias(Manual of Style))
*(alias(Tikiwiki Manual of Style))

{PARAM(name="structure")} {ELSE}{redirect page="{{page}}&structure=HomePage+Author"}{PARAM}