Wiki Web Best Practices

Wikis are, by design, anarchic in nature. When everyone can create content, there's often little in the way of organization involved. Organization requires the addition of guidelines and process.

Unfortunately, adding more process and guidelines can result in less freedom. It's a tradeoff. In order to improve organization and navigability, we need to ask content developers to exercise a little less creativity in creating pages, naming pages, and formatting pages.

The good news is that we're not going to tell you how to structure every page you create. And you'll reap the benefits of easier searches, better documentation, and a wiki web you might enjoy using.

Note: one of the features of our wiki software is the ability to set up multiple collaboration areas known as webs. Web owners can control much of the look and feel of their web without affecting anyone using other webs.

The remainder of this page can be viewed as a typical Wiki topic or as a slide presentation. For the slide presentation, just click the "Start Presentation" button.

Start presentation

Slide 1: Welcome to Our Web

A web is an area of collaboration, analogous to a folder on your desktop computer. The web is the part following /view/ in the URL.

Help is one of many webs in the the Wiki.

Having your own web allows you to customize many Wiki features.

Slide 2: The Most Important Thing

Anything that does not get regular attention will start to change for the worse. -- Mark Forster

No guidelines or best practices can help you if you don't follow them! Topics won't rename themselves to follw the naming conventions. Stale content won't magically clean itself up. Pages that are "accidentally" created with inappropriate parents won't miraculously rearrange themselves overnight.

The good (and bad) feature of a wiki is that there is no webmaster. There's no need to ask permission... but no one to tell you when you made a mistake (or help fix it).

You have three choices:

  • Appoint someone with the authority to rule. This person will be your wiki gardener - reviewing, pruning, weeding, and yes, repotting things planted where they don't belong. Give this person all the authority s/he needs to get the job done and your wiki will be tidy and navigable.

  • The "shared commons" approach. Everyone takes part in reviewing the wiki. Everyone takes the Best Practices to heart. Share the effort and share the rewards of a clean, navigable, wiki space.

  • Mix and match from both of the above. Everyone takes part but one person oversees the whole.

Slide 3: Features of a Well-organized Web

  • Planning - How should your web be organized?

  • Strong Topic Naming Conventions improve organization.
  • Content Guidelines and a standardized Template for new pages provide a consistent Look & Feel.
  • A customized Left Bar helps navigation.
  • Search Optimization - search is easier if things are designed to be found!
  • Entry Points aid navigation and improve organization.
    • Portal pages provide easy access to a set of related topics.
    • Dynamic indexes take advantage of naming conventions.
  • Authorized Access areas make certain pages available for team members only.

Slide 4: Naming Conventions and Topic Guidelines

Although naming conventions and page creation guidelines limit creativity a bit, they provide far better organization and easier navigation in the long run. Search results are especially improved by strong topic naming conventions. (Remember, you can still be creative in your content.)

See TopicGuidelines and ContentGuidelines for more ideas.

Slide 5: New Topics - Standardized Look & Feel

Every new topic page is based on a default template. By modifying a topic named WebTopicEditTemplate, you can change that default.

See WebTopicEditTemplateDescription for ideas.

Slide 6: Customized Left Bar

The Left Bar provides links to useful topics and related webs. The default left bar looks the same for every web. However, you can customize (or even remove) the left bar in your web or for a given topic.

Edit the topic, WebLeftBar, to customize the left bar for your web.

You'll need to use CSS to remove the left bar. See TWikiTutTricksWebLeftBar for details. (Use this trick with caution. Other people may expect to see the left bar. If they have a personal side bar, they'll be unhappy if you make it disappear!)

Slide 7: Convenient "New Page" Tool

This tool provides an easy default location if you just want to get started and don't want to worry about parent topics or related pages.

If you're creating one or more topics, but you're not sure where they will eventually be hooked up, start here. Don't worry too much about formatting when you begin. Just put in the content. Remember to preview your work on occasion.

When you've got your new topics(s) under control, ask for help in hooking them into the rest of our web tree.

Example: NewTopicCreate

Slide 8: Entry Points: WebHome

Every web has a WebHome topic. If you don't enter a topic name in the address field of the browser, you will see the WebHome topic by default. So

will take you to the same place as

Note: You're expected to edit WebHome, but please do not delete or rename the WebHome topic!

Additional Entry Points

The default entry point for your web is WebHome. However, different people may have different needs.

Example: a web configured to have two primary entry points

  • a Customer entrance (WebHome)
  • a Team entrance (linked from WebHome) for members of the core team

The customer entrance provides quick links to
  • Contacting the Team
  • Customer Support policies and procedures
  • Customer News and Information

The team entrance provides quick links to
  • a Read Me page
  • Guidelines
  • Team News and Updates
  • Team Directory

Additional Entry points provide more flexibility
  • by role ...
    • Team Portal
    • Property Operations portal
    • Manager's portal
  • ... or by interest areas
    • Project Management
    • Infrastructure
    • Security
    • Tips and Tools
    • ...

Slide 9: Search Control

Having your own web gives you better control over searches. When everything belongs to your team, you're less likely to get false positive hits.

Note that the simple search in the left-side navigation bar gives you the choice of searching by topic name or content (body text).

If a simple search isn't good enough, consider creating more advanced search pages, optimized for your usage.

Slide 10: Alternatives to Searching

Several handy topics are included in all webs:

Other topics can be added to improve navigation

  • Portals

  • Dynamic Indexes

Slide 11: Topic Tree

A TopicTree provides a "hierarchical" site map of a web or a portion of a web. The topic tree uses the Tree and TreeBrowser plugins to build a tree of "topic/parent" relationships.

NOTE: The "tree" is hierarchical only for purposes of navigation. On the server, a web is one folder, with all topics (pages) at the same level!

Slide 12: Portals

Portal pages can provide entry points and category indexing for sets of related topics or functional areas.

Slide 13: Dynamic Indexes

Dynamic indexes can provide up-to-date name-based indexing to topics that follow a strict topic naming convention.

Slide 14: Authorized Access Areas

Wiki access controls allow you to restrict read and/or edit access to one or more groups and/or individuals.

See WikiTutAccess for details.

Important: Wiki security isn't bullet-proof. Access controls are provided as a convenience, but they are not guaranteed. Do not place highly sensitive or confidential information in your web. In particular, if you are in Legal, Finance, or HR, you may want to talk to IT instead about more secure server options.

Slide 15: Useful Variables

Wiki variables are special text strings that expand "on the fly" to display user data or system information. Add variables to your web to make formatting even easier.

Variables are set with bullet syntax and evaluated by placing the word within a pair of %.


These three variables provide easy highlighting, underlining, and indentation.
   * Set HILITE = <span style="background-color: #FFFF66;">
   * Set ENDHI = </span>

   * Set UNDER = <span style="text-decoration: underline;">
   * Set ENDSPAN = </span>

   * Set INDENT = <div style="margin-left: 40px;">
   * Set ENDENT = </div>

%HILITE%This text is highlighted.%ENDHI%
This text is highlighted.

%UNDER%This text is underlined.%ENDSPAN%
This text is underlined.

%INDENT%This text is indented 40 pixels.%ENDENT%
This text is indented 40 pixels.


Perhaps you want to put your team name on every page but are concerned that your department will reorganize and the team name will change. Set a variable in the WebPreferences topic
   * Set TEAMNAME = The Kumquat Project Team

and use it anywhere you want to show the team name

     Our team is called %TEAMNAME%.

Our team is called The Kumquat Project Team.


See WebVariables for more ideas.

Slide 16: Don't Delete, Deprecate

Obsolete pages should be deprecated, rather than deleted, to preserve historical information.

Deprecated pages are marked and may be moved to another web if you prefer.

See HowToDeprecatePages.

Slide 17: Applications

Wiki applications

  • Aid organization, search, and retrieval of content

  • Automate workflow

  • Impose a consistent Look & Feel across a set of topics

We use wiki applications for

  • Team Directories

  • Calendars

  • FAQ pages

  • Status rollups

  • Project tracking

  • Runbooks

  • more...

Slide 18: References and Resources


-- VickiBrown -- 20 Jan 2010

Topic revision: r2 - 22 Feb 2013, VickiBrown
This site is powered by Foswiki Copyright © by the contributing authors. All material on this wiki is the property of the contributing authors.
Foswiki version v2.1.6, Release Foswiki-2.1.6, Plugin API version 2.4
Ideas, requests, problems regarding CFCL Wiki? Send us email