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
in the URL.
is one of many webs in our Wiki.
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.)
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.
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 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.
Entry Points: WebHome
Every web has a
If you don't enter a topic name in the address field of the browser, TWiki will use 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: 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
- 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
- Tips and Tools
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
Web Topic Trees
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 TWiki web is one folder, with all topics (pages) at the same level!
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 can provide up-to-date name-based indexing to topics that follow a strict topic naming convention.
Authorized Access Areas
TWiki access controls allow you to restrict read and/or edit access to one or more groups and/or individuals.
: 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
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 the team name will change in the future.
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.
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.
- Aid organization, search, and retrieval of content
- Impose a consistent Look & Feel across a set of topics
We use TWiki applications for