Wiki Usage Guidelines and Maintenance
The wiki
Philosophy
The
wiki
philosophy is based on
- Facilitating collaborations involving large teams
- Refactoring of ideas and information
- Convergence of text to correctness
- Ideas over esthetics
- Paying little attention to formatting until final document assembly
- Creating new pages as needed
- Using attachments only for images and finished documents (e.g., case report forms, finished protocols, published articles)
- Using plugins to extend basic functionality (e.g., tables, equations, bibliographic citations)
The
wiki
is a highly effective way of sharing information and working collaboratively. It favors content over esthetics and is ideal for multi-authorship and development of ideas, grant proposals, manuals of operation, documentation, and many other things. Unlike endless trails of e-mails,
wiki
is based on the belief that current available information is best, a central master copy of a document is a must, and ideas and information should constantly be
refactored. By
refactoring we mean that instead of accumulating an ever-lengthening document with streams of ideas, we make the stored information as valuable and easy to read as possible by deleting old information that has been replaced by new, or by updating old information. We rely on the change tracking feature to find out who changed what and when, and to roll back information to a previous version if the changes were found to be incorrect. The overall philosphy is that the authors having the most energy to update text are the ones possessing the appropriate information 90% of the time. There is a discussion forum for collecting more stream of conscientiousness type of information, but you are
highly encouraged to edit current content to add new ideas or to correct or clarify old ones. Do not feel shy about editing others' text, as the complete page history with time/date/author stamps is maintained. If you are about to make a major change in another's text or wish to reformat its appearance in a major way, it doesn't hurt to e-mail the author who has made the most changes to the page to get their opinion about your proposed changes.
Here is a
document giving more background and philosophy about the
wiki
way.
Creating Pages vs. Adding Attachments
Think of an attachment as a binary-formatted file (e.g., Word
.doc
file,
pdf
,
jpg
,
ppt
) that is in final form. Placing an attachment on a page implies that you are not seeking input from any reader of that page. Updating attachments requires re-uploading and re-attaching the document, which is time consuming. In addition, you lose the change tracking features of the wiki. In most cases you will find that adding content to an existing page or adding a new sub-page to an existing page (see Creating New
wiki
Topics below) is the way to go.
HintsTwiki shows you how save a final
wiki
page to open in
Word
, for example when creating a grant proposal.
As described below, it is best to use WikiWords to create new topics underneath the current page. Once you save your edits, a question mark will autoomatically appear to the right of the WikiWord. Clicking on the question mark will create the new (empty) page. Then you can start it, using for example:
%TOC%
---+ Title of New Topic
---++ Main Subdivision
* Description of first idea in main subdivision
* Description of second idea
* Description of third idea
---++ A Second Subdivision
---+++ A sub-sub section heading
* Ideas for sub-sub section
The above is how you would quickly enter simple markups using raw text mode. You can also use the
foswiki
WYSIWYG editor which has a lot of built-in help, but you'll find that this editor slows down the entry of content. The TOC directive above makes the wiki create an automatic table of contents at the top of the rendered page.
Creating New wiki
Topics
Think hard when naming a new wiki topic you create. See
HowToNameATwikiTopic for pointers. Especially note the following:
- It is seldom a good idea to have planned obsolescence in the name of a topic, e.g., a topic name that includes a date.
- Don't use generic topic names (e.g. AnalysisSummary) that others in the department might have wished to use in the future, unless you are operating on a separate project-specific wiki.
- In that case you may wish to define non-WikiWord topic names for important major categories using the following construct (topic name in first brackets, text to appear on web page in second):
---+++ [[Operations][Operations]]
* [[Meetings][Committee Meetings]]
- Try to organize notes from multiple meetings into a single topic to avoid creating a separate topic for each occurrence of the meeting. The TOC directive is a major help in this regard.
- Organize meeting minutes and related pages in reverse chronological order so that the most recent headings appear at the top.