Loading...
 

 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.



Tiki Manual of Style

Aka documentation guidelines

The Imperatives

The following rules are very important.



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, ((Wiki Style)) ).

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.

Wrong
!Adding a new user
Right
! 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.

Wrong
! Adding a New User
!!Fill the form

Fill and click.

!!Check the perms
Go to admin panel.
Right
! 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 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.

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 ((Tikiwiki Manual of Style)) |rules)) !" Right: Read the rules, which you'll find in ((Tikiwiki Manual of Style)) .


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:
      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. Below is the list of external wikis that we have defined in http://doc.tikiwiki.org:

Image

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 {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}^).
  • 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} is used to indicate a Tip, an hint or a special quote.
  • {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



Created by system. Last Modification: Wednesday 24 July, 2019 11:53:30 GMT-0000 by Yves Kipondo.

doc.tiki.org

Bootstrap AdminGuide UserGuide

Keywords

Keywords serve as "hubs" for navigation within the Tiki documentation. They correspond to development keywords (bug reports and feature requests):

Accessibility (WAI and 508)
Accounting
Articles and Submissions
Backlinks
Banners
Batch
BigBlueButton audio/video/chat/screensharing
Blog
Bookmark
Browser Compatibility
Link Cache
Calendar
Category
Chat
Clean URLs
Comments
Communication Center
Compression (gzip)
Contacts (Address Book)
Contact us
Content Templates
Contribution
Cookie
Copyright
Credit
Custom Home and Group Home Page
Date and Time
Debugger Console
Directory of hyperlinks
Documentation link from Tiki to doc.tiki.org (Help System)
Docs
Draw
Dynamic Content
Dynamic Variable
External Authentication
FAQ
Featured links
File Gallery
Forum
Friendship Network (Community)
Gmap Google maps
Groups
Hotword
HTML Page
i18n (Multilingual, l10n, Babelfish)
Image Gallery
Import-Export
Install
Integrator
Interoperability
Inter-User Messages
InterTiki
Kaltura video management
Karma
Live Support
Login
Logs (system & action)
Look and Feel
Lost edit protection
Mail-in
Map with Mapserver
Menu
Meta Tags
Mobile Tiki and Voice Tiki
Mods
Module
MultiTiki
MyTiki
Newsletter
Notepad
Payment
Performance Speed / Load
Permissions
Platform independence (Linux-Apache, Windows/IIS, Mac, BSD)
Polls
Profiles
Profile Manager
Report
Toolbar
Quiz
Rating
Feeds
Score
Search engine optimization
Search
Search and Replace
Security
Semantic links
Shadowbox
Shadow Layers
Share
Shopping cart
Shoutbox
Slideshow
Smiley
Social Networks
Spam protection (Anti-bot CATPCHA)
Spellcheck
Spreadsheet
Stats
Surveys
Tags
Task
Tell a Friend, alert + Social Bookmarking
TikiTests
Theme CSS & Smarty
Trackers
Transitions
TRIM
User Administration including registration and banning
User Files
User Menu
Watch
WebDAV
Webmail
Web Services
Wiki History, page rename, etc
Wiki Plugin extends basic syntax
Wiki Syntax
Wiki structure (book and table of content)
Workspace
WSOD
WYSIWYCA
WYSIWYG
XMLRPC

Tiki Newsletter

Delivered fresh to your email inbox!
Newsletter subscribe icon
Don't miss major announcements and other news!
Contribute to Tiki
Show PHP error messages