Define What a Wiki Is
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).
Some famous examples of wikis are Wikipedia and Wikileaks. The general public can contribute by adding and editing information on these sites. However, we are more interested in private wikis, which can only be seen and edited by the people in a company.
Wikis are ideal for storing business documentation because it is easy and quick to:
Create pages.
Edit pages.
See previous versions of pages.
Collaborate on a page together without losing the work of any contributor.
Create links between pages.
Organize material into hierarchies.
As you might have already guessed, wikis are the perfect place to store and manage all of agile documentation, including user stories and acceptance tests.
Understand the Benefits of Using a Wiki
To truly understand the benefits of managing documentation on a wiki, consider life without them (even just for managing 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.
Now someone in Tom's department updates the document in the Marketing Documents folder and gives the document a new name (ending in "v2").
I hope 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 created 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 Mary's changes. He simply navigates to the page and can see previous versions.
This is much better because the most recent version is obvious. It's easy for Tom to create the page and Mary and Patrick to edit and collaborate on it. If necessary, you can see each person's changes and previous versions.
Once you start using a wiki, you won't look back!
Choose an Agile Documentation Format
There is no one format for how to store and document agile requirements or related work. In this course we will use a wiki, which is a common practice. Many tools and lower fidelity mechanisms exist for documentation. Some things to keep in mind when creating agile documentation are:
Who will need to review this?
What questions will they most likely have?
How can I document this in a way that is kept current?
How long and how detailed does the documentation need to be? (Only create useful and valuable documentation.)
Find a Starting Point
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.
Let’s Recap!
There are many other formats for agile documentation outside of wikis, though it is the one we will use here. Our wiki principles will be universal.
A wiki is a website that has special features enabling collaborative editing by its users.
There are many benefits to using a wiki, notably quick access, real-time editing, collaboration, and version archiving.
The typical steps for storing documentation once the feature has been defined, are:
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 to create a Confluence page.
