Wiki Topic Guidelines

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.
  • Underscores are permitted (however, Wiki may complain "Not a WikiWord").
  • Avoid dashes, commas, and "special" characters (=!@#$%^&*+...).
  • Spaces are not permitted and will be removed.

** Wiki will not properly link names that begin with a lowercase letter, even in [[...]].

Important:

*Please remember that the CFCL Wiki is a shared resource. What you think might be a good name for your needs may clash with the requirements of another group, now or in the future. Try to be as specific as possible in choosing topic names so that there is no scope for any other group or project to have the same requirement.*

Avoid using a single word or acronym 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 as a page name (unless this is the canonical page for that tool).

Please also avoid ambiguous WikiWords such as TeamMeetings, BadgeDetail, ProjectCalendar, or MinorFeatures. Ask yourself: "Would someone doing a search be able to guess my project/property from the name of my page?"

If you break these rules, we will request that your page be renamed.

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 the Wiki. For guidelines and suggestions for creating content (aka documentation), in our Help web and elsewhere, please review Content Guidelines.

If you're new to the Wiki, you may want to begin by reading some introductory Wiki Docs.

Where To Create a Topic

The Wiki is organized into "webs" and "topics." A "web" is implemented as a directory (folder). Each web contains anywhere from 10s to thousands of topics.

Topics should be created in the most appropriate "web" Avoid putting project data into administrative webs such as Main or Sandbox.

If you are unsure which web you should be working in, consult a co-worker in your project team.

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:

breadcrumbs.jpg

Note: the Wiki implementation is very flat on the server side. Every topic in a web is at the same "level". 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 the 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 reasonable 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. Help), 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. NicksPage or VickiBrownTmp).

Use Meaningful Topic Names

We used to have a set of topics called GamesOpsTrainingSports, GamesOpsTrainingNews, GamesOpsTrainingWeather, 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 GamesOpsTraining was created, soon followed by a template page (mistakenly) named GamesOpsTrainingTemplate. 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

Technically, names containing underscores and names such as ABCFoo are not WikiWords; however, many automatically generated page names may contain underscores for easier reading. If you do use a non-WikiWord, be sure that it does include at least one underscore or at least two word "parts". For example: ProjectDetail200707p1_InfoSpec, YMGYdod.

(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.)

Topic Naming Conventions

TopicNamingConventions

Topic Naming Conventions

If your web, group, or project has a naming convention, stick to it.

(If you don't have a naming convention, this would be a good time to create one!)

If your page fits in an existing category of pages, please make that clear by including the relevant keyword, prefix- and/or -suffix when naming the page.

Type of Page Prefix Suffix Examples Notes
Customer related Customer   CustomerEntrance, CustomerNews "externally" facing pages
Focus Areas OnCall, Triage, Release...   OncallMasterHomePage, TriagePolicy, ReleaseCalendar Choose a prefix that clearly identifies the audience and type of content
Management related Mgmt   MgmtPortal, MgmtHeadcount Management areas,
not necessarily for use only by managers
may require Group privileges
Personal pages Personal     Personal pages are acceptable here.
Prefix topic name with Personal and be sure to
include your ID or name, e.g. PersonalVbrown, or PersonalVicki
Project related (general) Project   ProjectPortal, ProjectTracking  
Property or Subsystem related (specific) name of Property / Subsystem   FinanceBCP, SportsOps, FeedsOps standardized format
Team related Team   TeamPortal, TeamDirectory may require Group privileges





Portal (Entry) Page   Portal TeamPortal, ProjectPortal lots of links
BCP Procedures   BCP FinanceBCP  
FAQ   FAQ YMGParanoidsFAQ See the DocsFAQ index
Guidelines   Guideline(s) MeetingGuidelines, EmailGuidelines See the DocsProcedures index
How to... HowTo   HowToCloneNewServer See the DocsHowTo index
Index   Index ProjectArchReviewIndex usually uses a Search to produce an index
requires adherence to naming conventions
Open Issues tracking   OpenIssues PlatformOpenIssues, OpenIssues  
Policies   Policy EngrResponsePolicy See the DocsPolicy index
Procedures   Procedure(s) FinanceOncallProcedures See the DocsProcedures index
Processes   Process HRCSubmissionProcess  
Tools   Tools ToolsResource See the DocsTools index

Administrative (Restricted) Keywords

If you aren't completely confident of how these work, do not use these keywords in topic names!

Type of Page Prefix Suffix Examples Notes
Doc portals Docs   DocsGuidelines, DocsCustomer See the DocumentationLibrary index
Web admin Web   WebAttic, WebChanges  
Template   Template WebTopicEditTemplate Copy/paste or used by Wiki
See the DocsTemplates index; use this suffix with care
Template
strict creation mechanism
  TemplateStrict TriageMapTemplateStrict, ProjectDetailTemplateStrict Used via Form
Do not try to manually copy from these!

Create the 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.

Review the naming conventions and guidelines when 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://twiki.corp.company.com/view/Projex/MyWonderfulPage

If the page doesn't exist, the 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 logical hierarchy of a site. (See TopicTree for an example.) Be sure to set the parent topic appropriately (Details).

Use a Form

You can also set up a form with a button to make creating new topics easier. If you like, make a copy of this page: Help.NewTopicCreate in your own web.

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 the Wiki first. Read over some of the docs that are included, 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, the 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, the Wiki will "sign it" with your name and the current date and time (in GMT). This information appears in the upper right corner 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 revision. 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?

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

If you choose to make your changes anyway, the 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 fix 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.

Editing Enhancements

It can be frustrating to type text into a browser window. Remember that you have more control than you think.

Warning: Can't find topic Help.TipsTWiki

Content

Starting a New Page

See HowToCreateNewPages if you're not sure how to begin.

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, the 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: r2 - 22 Feb 2013, 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