Wiki Topic Guidelines

These guidelines pertain to either TWiki or Foswiki. When you see the word "Wiki", substitute the specific platform in your head as you read.

If you don't read anything else, read this!

Follow WikiWord syntax when creating new pages. A WikiWord consists of two or more words with initial capitals, run together.

Always begin your page name with a capital letter. Use two or more words, or acronyms and words, in CamelCase.

Important:

Never use a single English word as a page name! For example "Availability", "Hosts", "Monitoring", and "Misc" are all bad names (which have been tried!). Likewise, avoid using a single tool name or acronym as a page name, unless this is the *primary page that discusses that tool.*

A Wiki page is also called a topic. By default, anyone can create new topics (or edit existing topics) anywhere in the Wiki site.

This page describes naming conventions and other guidelines for creating topics in Wiki. For guidelines and suggestions for creating content (aka documentation), in our Learn web and elsewhere, please review Content Guidelines.

If you're new to Wiki, you may want to begin by reading the Wiki tutorial.

Where Am I?: The Breadcrumb List

At the top of every Wiki page is a list of "breadcrumb" links that show you where you are in the (logical) Wiki page hierarchy. Each element of the breadcrumb list is a link, so you can easily work your way back up the tree. Example:

Breadcrumb list

Note: the Wiki implementation is very flat on the server side. Each "web" is implemented as a directory (folder). Everything else is a file. The breadcrumbs represent a logical organization. In reality, all pages in a web are actually stored at the same level, in a single namespace.

Topic Naming

Choose Topic Names With Care

In Wiki, everyone has write access to most of the site. Please remember that you're sharing with a LOT of people! Imagine if all developers shared one CVS directory. Think of the potential problems in naming source files.

Before naming a Wiki page, take some time to consider a meaningful name. If you create a page with a general-seeming name, people will have a resonable expectation that this page applies to the entire surrounding "web". Unless you're creating a page that you expect to be of utility across the current web (e.g. Learn), choose a more narrowly-focused naming convention. Think carefully before creating pages with names like StatusReports, MeetingMinutes, ActionItems, or ProjectPlanning!

If you create a page for your group's quarterly goals, don't name it QuarterlyGoals (Hint: whose quarterly goals are these? How can you tell?). Include your team's name, project name, and other useful identifying information in the topic (page) name! Pages created by individuals for "personal" use should include your name in the topic name (e.g. NicksOncallPage).

Use Meaningful Topic Names

In previous job, I discovered a set of topics called GamesTrainingSports, GamesTrainingNews, GamesTrainingWeather, etc. You couldn't guess it from the names, but none of these pages was games-related! I can only guess that the weird convention started when GamesTraining was created, soon followed by a template page (mistakenly) named GamesTrainingTemplate. Everything cascaded from there.

Try to choose meaningful topic names. If your topic is general in scope, use a more general name. If the scope of a topic changes, you can rename it. Renaming is relatively easy to do; just click the "More Topic Actions" link at the bottom of the page and review your options.

Use WikiWords for Topic Names

Follow WikiWord syntax when creating new pages. A WikiWord consists of two or more words with initial capitals, run together.

Always begin your page name with a capital letter. Use two or more words, or acronyms and words, in CamelCase.

Important:

Never use a single English word as a page name! For example "Availability", "Hosts", "Monitoring", and "Misc" are all bad names (which have been tried!). Likewise, avoid using a single tool name or acronym as a page name, unless this is the *primary page that discusses that tool.*

(Note: You must reference non-WikiWord topics inside double brackets, e.g. [[Not_Quite_Standard]]. We recommend that you make a habit of always using the double brackets in any case ([[MyPerfectPage]]. It makes the web more manageable.)

How To: Create a New Topic

To create a new page, first create a link.
  1. Choose a related page that already exists.
  2. Edit the existing page
  3. Add your new page name to the existing page.
    • Use of double bracket syntax, [[PageName]] is recommended.
  4. Save

See above for naming conventions and guidelines to choosing names.

Alternatively, enter the Name in the Address Field

Alternatively, you can create a new page by simply trying to access it from the address field of your browser
   http://wiki.company.corp/view/Team/MyWonderfulPage

If the page doesn't exist, Wiki will ask if you want to create it.

Note Pages created this way are "orphans". They are not connected (yet) to any other page and their parent topic is the default top of the web. The parent relationship is important; it forms the basis of the "breadcrumbs" shown at the top of every page. In addition, the TreeBrowserPlugin relies on topic parent/child relationships to present a logicall hierarchy of a site. (See WebTopicTree for an example. ) Be sure to set the parent topic appropriately (Details).


Editing Pages

Use the Edit link (upper right or lower left) on any Wiki page to open that page for editing. You should probably familiarize yourself with Wiki first. Read over some of the docs that are included with Wiki, e.g. the Formatting Help and Good Style guidelines. Note these two documents are linked from the "help" section at the top of every Wiki editing page. That section also provides basic formatting hints. If you don't see the Formatting Help section, click the Show Help link just above the white editing area.

show help

Tracking Edits

When you click the Edit link, Wiki starts a 60-minute "timer" for you. This 60-minute timer is used for version history (below) as well as for notifying others that you have the page open for editing. During this period, Wiki believes that you are editing that page, even if you click away to another page or close the Browser window.

When you save the page, Wiki will "sign it" with your name and the current date and time (in GMT). This information appears in the upper right coorner of each page.

Version History

Wiki uses RCS to save previous revisions of a topic. All changes you make (and save) during one 60 minute period will be "rolled into" one saved revsion. You can view those revisions, as well as the complete version history, using the appropriate links at the bottom of the "view" page.

screenshot

Note that past versions of a topic are not editable. If you want to revert to a previous revision, view that revision in "Raw" mode (see below), copy the section you want, and past it into a new "Edit" session for the topic.

What Happens if Two People Edit The Same Page?

Wiki will notify you if you try to edit a page that someone else has open for editing. You can choose to wait, to edit anyway, or to contact the other person and arrange a mutually convenient time to edit.

If you choose to make your changes anyway, Wiki will try to merge both sets of changes together. It usually does this correctly; however, you should always review the page carefully to be sure no mistakes were made.

If You Don't Make Any Changes

If you decide to leave an "Edit" session without making any changes, be sure to click "Cancel" (at the bottom of the page) instead of simply using the Back button in your browser. When you Cancel, the 60-minute timer is reset. Otherwise, anyone else who tries to edit the page will receive a notice that you have it open!

Preview Before Saving

You can preview your page before saving, then go back and fis anything you don't like. Just click the Preview button at the bottom left of the Wiki edit screen.

Raw View (or, How Did They Do That?)

If you just want to take a peek at the underlying code for a Wiki page, use the "Raw View" link at the bottom of the page. This gives you "read-only" access to the page contents without starting the 60-minute timer.

Parent Topics

The breadcrumb list shows the "parent" relationships for the current topic. These relationships make it easier to navigating the web.

By default, a topic's "parent" is the page from which you first linked to it. If you create a topic "from thin air" (e.g. via a "page does not exist, do you want to create it" form), the parent will be set to the "WebHome" topic of the current web.

You can change a topic's parent to make navigation easier. Keep in mind that you are changing a logical relationship when you do this. Nothing is actually being moved around on the server.

To set the parent topic, click More topic actions at the bottom of a "view" (not "Edit") page. Then scroll down to the item, Set New Topic Parent.

SetParent.png


Content

Content Guidelines

Be sure to review the Content Guidelines. The guidelines provide recommendations and references for writing topic content.

New Topic Edit Template

When you create a new topic, Wiki starts you out with a standardized "new page" template. This template can vary considerably depending on which Web you're in when you create a new topic.

Topic revision: r3 - 02 Jan 2016, VickiBrown
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding CFCL Wiki? Send feedback