Wiki Usage Guidelines and Maintenance

View a Wiki presentation by Cole Beck: VIDEO

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.


Creating a New Wiki Page that is Linked to an Existing Page

The easiest way to do this is as follows:
  • Click on "Raw Edit" at the bottom of the existing page.
  • Enter the WikiWord name for your new page and an English descriptor of this page using the following syntax:
    [[ThisIsAWikiWordName][This is the English descriptor of my new page]]
  • Click the Save button to exit from editor mode. You will now see your English descriptor followed by a blue question mark. Clicking on this question mark creates you new page, which will be properly linked to the old one.
Topic attachments
I Attachment Action Size Date Who Comment
wikiway.pdfpdf wikiway.pdf manage 124.3 K 30 Aug 2009 - 12:13 FrankHarrell Background and philosophy of the wiki
Topic revision: r6 - 16 Jan 2014, DalePlummer
 

This site is powered by FoswikiCopyright © 2013-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Vanderbilt Biostatistics Wiki? Send feedback