Documentation Guidelines

From OSF Wiki
Jump to: navigation, search

To enter or update content on this wiki site, follow these summary steps, with more detail below:

  1. Generally be familiar with the pages and categories of this site, including generic templates
  2. If your desired content is missing, create a new page
  3. When creating a new page, check to see if it fits within one of the standard "template" formats used on this site
  4. If your desired content exists, but requires updating or expansion, then edit that page
  5. Establish useful cross-links, including defining new concepts
  6. Make sure your page is properly categorized into the wiki structure
  7. Sign-off and mark the page as complete.

Become Familiar with the Wiki Content

A number of sources can help you get familiar with this site:

Become Familiar with Generic Templates

Some parts of this wiki, such as concept articles and others, have multiple entries with very similar formats and organization.

There are also templates on this wiki, which can be a valuable source for reusing content and structure. To become familiar with the available templates:

  1. Click Special Pages > All Pages
  2. In the Namespace list, choose Template and click Go.

Create a New Page

Please follow these steps when creating a new page:

  1. Name each new content page with a title in Initial Caps, similar to the titles of other content in its same type or category. You need not enter underscores '_' for spaces in the title; they will be entered automatically
  2. Use and follow an existing template if one exists and is applicable
  3. Begin editing using your preferred editing format, using either straight wikitext, the WikED option or the rich text editor
  4. Until a page is fully vetted, note it as incomplete. You do so by placing the {{Unchecked}} statement as the first line in your new page when editing
  5. Always keep the first paragraph as the general lead in or abstract covering the material in the page
  6. Make sure and bold the topic of the page, such as, for example, Create a New Page in the context of this section, that highlights the topic title of that page
  7. Write and author in the active voice; please keep sentences short
  8. Make meaningful cross-links wherever possible.

Suggestions for Collaborative Authoring

In initial formulation, it can be productive to have two persons -- an instructor and a recorder -- work together to enter new content. In this mode, the instructor works through the steps and provides links, etc., useful to the content, while the recorder takes notes directly on the appropriate wiki page.

Here are some useful suggestions:

  1. Prior to the session, it is useful for the instructor to set up the initial page(s) and outline the content in the wiki according to its appropriate format or template.
  2. During the session, the recorder should record to a duplicate version of the page in edit mode, so that the instructor can see the original version. After the session, the recorder can save the edited version, which will then update the content
  3. Both recorder and instructor can later access the page to provide subsequent editing or format updates.

Edit an Existing Page

Please follow the guidelines for creating a new page in your edits.

You should also consult the general editing guidelines for proper use of wikitext syntax, available formatting options, etc.

Link to or Define Concepts

A key strength of a wiki is the ease of making cross-links to other articles and concepts. Please do so aggressively as you author.

Cross-linkages

Try to make internal cross-links where appropriate and useful. Keeping up to date with the page content on this site is quite important. If you are a regular user of the wiki, then often inspect Recent changes, always shown in the left-hand panel. That should be sufficient to keep you current on content changes.

External linking is also important. Please try diligently to relate the material you author to broader topic material on the Web, especially but not limited to Wikipedia.

Note there is different syntax and format for internal v external links. See this description.

Define a New Concept

One of the largest categories of articles on this wiki are the concept articles. These define important terms and provide backup for the terminology used herein.

This category is one of the most important to be familiar with, since its content is a valuable source of internal linkages for your articles. If you use one of the terms in this category in your documentation, please link to it.

You may also find on occasion that a term you want to frequently use is NOT already in this category. If you suspect this term may be used on more than three (3) pages eventually across this wiki site, then you should add a new Concept Article.

You do so in the following manner:

  • Name the page as 'XXX Concept', with XXX being your new desired term (or acronym)
  • Follow the standard page creation and editing guidelines
  • Provide a descriptive lead-in paragraph or three, relating the term or concept to its role and use in this wiki
  • If the term or concept is contained in Wikipedia, provide the cross-reference linkage template at the bottom of your edits. It has this standard form:
 <!--This links into Wikipedia Content----->
 {{WP}}
 
 {| border="1" cellpadding="5" cellspacing="0" class="wikitable" style="text-align:center" {{Prettytableb}}
 |-
 ! <anyweb>http://en.wikipedia.org/wiki/Resource_Description_Framework</anyweb>
 |}
  • Categorize the article under its appropriate Topic Category and check it as well in the Concept Article category.

Categorize the Page

If you are quite familiar and comfortable with the intent and scope of this wiki's category structure, go ahead and add category assignments to each new article. The available categories are shown in nested order with checkboxes below the standard editing text area when editing a page.

Please note that the Topic Categories category solely pertains to the topic of the page; each page should also be assigned as well to another non-topic category.

HOWEVER, if you are not comfortable with the overall category structure, simply assign your new page to the Uncategorized category, shown at the bottom of the category listings below the standard editing text area when editing a page. An admin will later make the assignment of the page into its proper category(ies).

Vet the Page as Complete

Unchecked pages are those which have not been fully vetted and checked for:

  • content
  • formatting
  • images
  • categorization, or
  • internal cross-linkages.

So long as a page is Unchecked (not vetted), the page is automatically placed into the Unchecked category. Please see that category for all such pages.

If, after following the guidelines above, you have deemed all of these checks to have been met, then you should mark the page as complete. You do so by removing the {{Unchecked}} template call at the top of subject page. Once removed, the notice will no longer appear on the page and it will not be retained in the Unchecked category.

Site Structure and Organization

ZWiki
Drupal
FME
GATE
Help
Icons
Images
IrON
Logos
Search
UMBEL
Vision