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 TWiki web you might enjoy using.

Note: one of the features of TWiki 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.

Welcome to Our Web

In TWiki, 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.

Learn is one of many webs in our Wiki.

   http://wiki.cfcl.com/bin/view/Learn

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

The Most Important Thing

No guidelines or best practices can help you if you don't use them! Topics won't rename themselves to follow 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 jb 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 pain (small) 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.

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.

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 WikiTopicGuidelines and ContentGuidelines.

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.

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!)

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

Entry Points: WebHome

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

   http://wiki.cfcl.com/bin/view/Learn

will take you to the same place as

    %SCRIPTURL{"view"}%/Learn/WebHome

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: The "Operations" web is configured to have three primary entry points

  • a Customer entrance (WebHome), for Engineering developers and managers
  • a Team entrance (linked from WebHome) for members of the core team
  • an OnCall Master Home page (linked from the Team Entrance) is the primary entry point for On-Call Service Engineers.

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
    • OnCall Portal
    • Property Operations portal
    • Manager's portal
  • ... or by interest areas
    • Project Management
    • Infrastructure
    • Paranoids/Security
    • Tips and Tools
    • ...

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.

Alternatives to Searching

Several handy topics are included in all webs:

Other topics can be added to improve navigation

  • Portals

  • Dynamic Indexes

Web Topic Trees

A WebTopicTree 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 TWiki web is one folder, with all topics (pages) at the same level!

Portals

Portal pages can provide entry points and category indexing for sets of related topics or functional areas. Each portal page provides a top-level "home" for a topical area, such as OnCall, Projects, Security, Infrastructure, Managers, etc.

Dynamic Indexes

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

Example: DocsGuidelinesIndex

Authorized Access Areas

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

See WikiTutAccess for details.

Important: TWiki's 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.

Useful Variables (Macros)

Wiki variables (aka macros) 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 %.

Examples

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.

Example

Perhaps you want to put your team name on every page but are concerned that the team name will change in the future. 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.

More...

See Macros for more ideas.

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.

Applications

TWiki applications

  • Aid organization, search, and retrieval of content

  • Automate workflow

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

We use TWiki applications for

  • Team Directories

  • Calendars

  • FAQ pages

  • Status rollups

  • Project tracking

  • Runbooks

  • more...

Topic revision: r2 - 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