What is a wiki?
A wiki is a website that has special features enabling collaborative editing by its users. In the corporate domain, wikis are typically used as a central platform for sharing information with a team (e.g. employees).
The word 'wiki' comes from the Hawaiian language and means 'quick'. When Ward Cunningham created the first wiki, he wanted people to be able to quickly create web pages to store information online and collaborate without having technical knowledge like HTML. Wikis are ideal for storing business documentation because it is easy and quick to:
Create a page
See previous versions of pages
Collaborate on a page together without losing the work of any contributor
Create links between pages
Organize material into heirarchies
As you might have already guessed, wikis are the perfect place for us to store and manage all of our agile documentation including user stories and acceptance tests.
Benefits of using a wiki
To truly understand the benefits of managing documentation on a wiki, let us consider life without a wiki, even just for managing some text files or spreadsheets.
The file on a server approach
Tom creates a text file called "Legal Resources"and saves it on the company's server in a folder called "Marketing Documents".
Mary works in the Legal department and does not have access to that folder. Tom emails it to her and she keeps a copy on the company server in a folder called Legal Marketing Docs.
Mary makes some changes to the file. Tom cannot see these changes as he has access to a different version of the document.
Now someone in Tom's department called Patrick updates the document in the Marketing Documents folder and gives the document a new name (ending in "v2").
I'm hoping you can see how this gets messy very quickly. Imagine if your company has ten thousand employees. How do you identify the most up-to-date version of a document?
The wiki approach
Tom creates a new wiki page called "Legal Resources for Marketing team"
Mary wants to see this page.
Tom emails her a link.
Mary makes some edits. Anyone who visits this page will now see the updated page immediately.
Patrick makes some changes. Anyone who visits this page will now see the updated page immediately.
Tom wants to see what changes Mary had made. He simply navigates to the page and can choose to see previous versions.
This is much better because it is obvious which is the most recent version of the page. It is easy for Tom to create the page. It is easy for Mary and Patrick to edit and collaborate on the page. If necessary, you can see each person's changes and previous versions.
Once you start using a wiki, you won't look back!
Agile Documentation Format
When we store our agile documentation, we will adhere to 'Agile Documentation Format' which mandates that:
Each user story has its own wiki page.
The acceptance tests for a given user story appear on the wiki page of that user story.
Features (which can be thought of as sets of user stories) have their own wiki page with a link to each user story encompassing the feature.
The natural starting point for storing documentation is to take one feature (which contains several user stories) and:
Create a wiki page for the feature.
Create wiki pages for each user story.
Add links to each user story on the feature page.
Add acceptance tests to each user story page.
In the next chapter, we will go through these steps in order.