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.
Slide 1: Welcome to Our Web
is an area of collaboration, analogous to a folder on your desktop computer.
The web is the part following
in the URL.
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 Topic Guidelines
and Content Guidelines
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
, you can change that default.
See Web Topic Edit Template Description
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,
, to customize the left bar for your web.
You'll need to use CSS to remove the left bar. See TWiki Tut Tricks Web Left Bar
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.
Slide 8: Entry Points: WebHome
Every web has a
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
: 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 (
- 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
- 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
- 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
Slide 11: Topic Tree
A Topic Tree
provides a "hierarchical" site map of a web or a portion of a web. The topic tree uses the Tree
plugins to build a tree of "topic/parent
: 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.
: 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
* 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.
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.
Slide 17: Applications
- Aid organization, search, and retrieval of content
- Impose a consistent Look & Feel across a set of topics
We use wiki applications for
Slide 18: References and Resources
-- 20 Jan 2010