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!