Posted by m.jackson on 24 March 2016 - 10:47am 

By Mike Jackson, Software Architect.

My EPCC colleague, George Beckett, recently e-mailed me to comment that "I'm conscious that wikis typically deteriorate into a mess of conflicting/out-dated materials, if not managed closely". George asked whether the Institute had advice on good practices for using a wiki. So, for George and others with wiki worries, here are our top tips on using a wiki for a software project...

1. Start as you mean to go on

Create some order at the outset and draw up an outline of the key areas of the wiki (e.g. Project Management, Dissemination, Design, Development etc.) and what they will contain, then create these areas on the wiki.

2. Appoint an editor

Your editor will "own" the wiki, manage its structure and regularly review, police, and tidy the wiki. The editor can help to ensure that your wiki remains structured and that your users respect the following tips...

3. Don't accidently create WikiWords

Wikis treat words in CamelCase (e.g. GitHub, SciPy) as WikiWords and create links to new child pages for these words, which appear as "WikiWord?" until a child page is created. These can make your text more difficult to read. Wikis provide annotations to tell the wiki when a word in CamelCase is not to be treated as a WikiWord.

4. Create child-pages for WikiWords there and then

If you intentionally create a WikiWord for a new child page, then create the child page there and then. On which note,

5. Provide content for pages

Don't create a page unless you have content for it. It is a waste of others' time if they have to navigate through a barren land of empty pages looking for information that has not been added. And, "To be added" or, even worse, "Under construction" (that's so 1990s!) is not content, as you know, deep down, you won't return to these!

6. If in doubt, ask your editor

If you are unsure of where to create a new page or put some information, ask your editor.

7. Check to see if content is already there

Before creating a new page, or adding new content, search to see if a suitable page, or that content, has already been added by another user.

8. Avoid redundancy

If you're considering adding something, first look at what it might be useful to remove for clarity.

9. Update the status of ideas and designs

Wikis are often used to capture ideas and designs. Some of these will remain as unexplored ideas, some will be explored as designs but then discarded, and some will be implemented. It can help to avoid confusion in the future if you document, and update, the status of ideas and designs, to make such distinctions clear.

10. Add version numbers for software, tools, languages, operating systems, specifications, protocols or standards

When you say "Linux" do you mean Scientific Linux 7 or Ubuntu? When you say "Python" do you mean Python 2 or 3, or both? When you say "C compiler" do you mean GNU, Cray or Intel C compilers? Specifying version numbers can help prevent others' from wasting time using incompatible, or unsupported, versions.

For more top tips, see PBWorks Tip of the Week #1: Five Ways to Manage Your Wiki Better.

That completes our top tips on using a wiki, but, as always, please let us know what you think!