9.6 Wiki Standards

There are so many ways of using wikis that we need to agree on standards.

Formatting Conventions

These are the most used conventions in the wiki for formatting.

Command Line Examples

Confluence has a built in macro specifically for command line examples. For command line examples, use the code macro set to the language bash. Also for in-line comments, use the # symbol which is ignored on the command line.

# Here is an example of the ls where -l specifies list and -h specifies to print sizes in human readable format (e.g., 1K 234M 2G)
ls -lh
total 5004
drwxr-xr-x  2 svradm svradm    4096 2010-04-12 22:44 .
drwxr-xr-x 10 svradm svradm    4096 2011-02-02 12:45 ..
-rw-r--r--  1 svradm svradm   15240 2010-03-09 12:06 annotations-api.jar
-rw-r--r--  1 svradm svradm   53752 2010-03-09 12:06 catalina-ant.jar
-rw-r--r--  1 svradm svradm  128482 2010-03-09 12:06 catalina-ha.jar
-rw-r--r--  1 svradm svradm 1185418 2010-03-09 12:06 catalina.jar
-rw-r--r--  1 svradm svradm  234968 2010-03-09 12:06 catalina-tribes.jar
-rw-r--r--  1 svradm svradm   32384 2010-03-09 12:06 el-api.jar
-rw-r--r--  1 svradm svradm  108557 2010-03-09 12:06 jasper-el.jar
-rw-r--r--  1 svradm svradm  524432 2010-03-09 12:06 jasper.jar
-rw-r--r--  1 svradm svradm 1408191 2010-03-09 12:06 jasper-jdt.jar
-rw-r--r--  1 svradm svradm   76634 2010-03-09 12:06 jsp-api.jar
-rw-r--r--  1 svradm svradm   88224 2010-03-09 12:06 servlet-api.jar
-rw-r--r--  1 svradm svradm  758643 2010-03-09 12:06 tomcat-coyote.jar
-rw-r--r--  1 svradm svradm  232855 2010-03-09 12:06 tomcat-dbcp.jar
-rw-r--r--  1 svradm svradm   69932 2010-03-09 12:06 tomcat-i18n-es.jar
-rw-r--r--  1 svradm svradm   51851 2010-03-09 12:06 tomcat-i18n-fr.jar
-rw-r--r--  1 svradm svradm   54920 2010-03-09 12:06 tomcat-i18n-ja.jar

Also when the command line is simply use as a point of reference, it is often useful to make it collapsible

# Here is an example of the ls where -l specifies list and -h specifies to print sizes in human readable format (e.g., 1K 234M 2G)
ls -lh
total 5004
drwxr-xr-x  2 svradm svradm    4096 2010-04-12 22:44 .
drwxr-xr-x 10 svradm svradm    4096 2011-02-02 12:45 ..
-rw-r--r--  1 svradm svradm   15240 2010-03-09 12:06 annotations-api.jar
-rw-r--r--  1 svradm svradm   53752 2010-03-09 12:06 catalina-ant.jar
-rw-r--r--  1 svradm svradm  128482 2010-03-09 12:06 catalina-ha.jar
-rw-r--r--  1 svradm svradm 1185418 2010-03-09 12:06 catalina.jar
-rw-r--r--  1 svradm svradm  234968 2010-03-09 12:06 catalina-tribes.jar
-rw-r--r--  1 svradm svradm   32384 2010-03-09 12:06 el-api.jar
-rw-r--r--  1 svradm svradm  108557 2010-03-09 12:06 jasper-el.jar
-rw-r--r--  1 svradm svradm  524432 2010-03-09 12:06 jasper.jar
-rw-r--r--  1 svradm svradm 1408191 2010-03-09 12:06 jasper-jdt.jar
-rw-r--r--  1 svradm svradm   76634 2010-03-09 12:06 jsp-api.jar
-rw-r--r--  1 svradm svradm   88224 2010-03-09 12:06 servlet-api.jar
-rw-r--r--  1 svradm svradm  758643 2010-03-09 12:06 tomcat-coyote.jar
-rw-r--r--  1 svradm svradm  232855 2010-03-09 12:06 tomcat-dbcp.jar
-rw-r--r--  1 svradm svradm   69932 2010-03-09 12:06 tomcat-i18n-es.jar
-rw-r--r--  1 svradm svradm   51851 2010-03-09 12:06 tomcat-i18n-fr.jar
-rw-r--r--  1 svradm svradm   54920 2010-03-09 12:06 tomcat-i18n-ja.jar

Code Examples

We use the same macro but select the particular language to used in the example.

Collapsible Content

Collapsible content using the expand macro should only be used in cases where the reader wants to quickly view optional data. A good example is an FAQ. Beyond that, consider simply making a link to another page.

Author Notations Calling for Action

These are notations used by authors to note parts of the wiki that are not yet ready or need improvement.

Action Items

All action items use the warning macro and are aimed at other authors or letting the reader know the contents are not quite complete or need improvement. Action items should all use a title of "Action Item" followed by a classification. This allows us to easily search for action items.

The Bonsai Wiki Standards uses the heading of the warning marco with the following code,

• TBC (To Be Completed) - Follow with a name if appropriate.
• TBI (To Be Improved) - Help Improve the Article
• TBR (To Be Reviewed) - The Author Would like Review by Peers. Follow with a name if appropriate.

Here is an example of an action item that talks about improving content with examples,

Notes

The purpose of notes is to highlight information. We use the notes macro for this.

References and Hyper-links in Notations

We use the Info macro to provide informational comments that may be of interest to the reader but not required reading. This is different than direct references which should just be normal html links.

Panels

The Panel Macro allows you to display anything from a block of text, to an image or embedded video inside a customizable panel. Generally, the purpose is to accentuate content or define sections within a page.

Directory Structure Highlights for Authors

Authors of content should know about the areas of the wiki and how we place the content as it is being written and organize completed content.

Re-Using Content

Confluence's Include and Excerpt Include macros help you re-use content. However, keep in mind that changing the page title of an include will break references.

Writing Content

Dictionary - Canada English

Capturing Images

Browser Windows

Go to, http://resizemybrowser.com/ and click on the appropriate link to resize the browser window to 800 x 600 dpi (dots per inch).