Using the zWiki

From OSF Wiki
Jump to: navigation, search

This document provides general guidance on how to use and maintain a zWiki, including best practices and the use of some conventions. Document writers and contributors to a zWiki are the audience for this document.

1. Become Familiar with Wiki Syntax

The zWiki, based on the MediaWiki software, uses wikitext as its basic authoring and editing syntax. (You can use WYSIWYG and semi-WYSIWYG editors -- see below -- but all basic content is ultimately stored and managed as wikitext.)

The first place to become familiar with the wiki framework is the Mediawiki user's guide. Basic Wiki Guidance is the place to first familiarize yourself with the wiki aspects of this site. General wikitext syntax and editing guidance is provided by the editing guidelines.

2. Edit and Author Documents

A series of three documents -- with some overlap -- provides guidance on how to author and edit articles on this wiki:

Prior to entering or modifying any content, it is recommended you read these three documents.

Choosing an Editor

When editing and modifying articles, you have the choice of three options:

  1. Use of the native wikitext; this is often easiest for small edits or articles because there is less overhead
  2. The semi-WYSIWYG WikED editor assist, which requires Firefox and Greasemonkey. This helps automate some tasks and provides some code highlighting, but is less than a complete, standard editor, and
  3. Use of a rich text editor that provides a true WYSIWYG option. This latter option may provide a more "standard look and feel" but it does impose overhead and sometimes does not work smoothly.

The links above explain how to basically install and configure these options. Consult your system administrator for more detail on these choices.

3. Assign Categories

As the guidelines above emphasize, try to fully and accurately tag your document content with appropriate categories. You may do so via the standard wikitext tagging convention of [[Category:My Category]].

In addition, three other category conventions should be kept in mind:

  • Apply [[Category:Restrict]] when you have draft content that should only appear to administrator users (removing this tag makes the document "public")
    Important yellow.pngThis page is unchecked !!!
  • Apply the special template code {{Unchecked}} to put a notice in the document such as the one to the right, which also flags the content for checking by a system administrator, and
  • Always assign the category [[Category:zWiki]]; this is a convenient means for globally flagging content deserving of export.

4. Follow Style Guidelines

The document Basic Wiki Guidance provides some standard style guidelines that should be followed. The Editing Guidelines also show some pre-loaded styles (for highlight boxes and such) that can also be embedded within your articles. Consistent use of the prepared styles and consistent use of header levels with initial caps will help ensure presentation uniformity across articles.

A special case is when code is being quoted or embedded within a document. In those cases, please follow the guidelines in the Code Highlighting document. Simple examples are provided in that document.

Consistent use of these styles means that the wiki content can be re-purposed consistently for other purposes and publications. More on this topic is provided in the zWiki as a Publishing Platform document.

5. General Use Tips

In addition to these authoring guidelines, here are some other tips.

Uploading Images

Images may be uploaded and made available for embedding in documents via the Upload file link shown to the left. This link enables you to identify an image file on your local file system and upload it to the wiki. If you do not manually change the name, it will use the file name on your local system.

It is obviously best to use a descriptive, yet short, name for your image files. Image files may be of virtually any starting size and in the formats of *.png, *.gif, *.jpg, *.jpeg, *.doc, *.xls, *.pdf, *.ppt, *.zip, and *.svg. (These may be changed in your configuration settings file.)

For presentation purposes, it is recommended that images larger than 600px wide be resized and centered when placed into a document. An example of this format is:

        [[file:MyImage|center|600px]]

Converting Existing Text

Your starting text may be in other formats that you wish to convert to wikitext for pasting. A variety of converters is listed on this wiki under the wiki converters.