Write Agile Documentation: User Stories & Acceptance Tests

Popular Wiki Products

There are several wiki products out there that are worth considering, such as:

• Confluence - developed by Atlassian, this is by far the most popular wiki.

• Notion - a wiki with great design and free to use (until you reach a certain number).

Both are free for personal use. In the next chapters you’ll be learning how to create a wiki. To do this, you’ll need to create a Confluence or a Notion account. Let’s take a look at how to do this with Confluence right now.

Set Up Confluence

There are a few steps to creating a wiki with Confluence:

First, create an account on Confluence using this link. 

Then, enter your e-mail address and click on Sign up. You may receive a verification email: click on it if it has arrived.

Congratulations, you’ve created your account! Now, let’s look at how to create a space called Product. Spaces are areas you can create in Confluence for specific purposes. For example, you would store marketing documentation in the marketing space and product documentation in the product space.

Next, you can name your new space.

And finally, here’s where you can create your first wiki page!

Create Your First Wiki Page

Let's go back to an example from a previous chapter:

1. We decided to look at a feature (called a quiz). 

2. We went through a process to write 14 user stories for this quiz feature.

3. We then wrote acceptance tests for some of these user stories.

Now, let's use a Confluence wiki to store this information so the team can access it:

1. Create a wiki page for the quiz feature. 

2. Create 14 user story pages.

3. On the Quiz page, write down the user stories and add a link to each individual user story page.

4. Add the acceptance tests (that belong to a given user story) on that user story's page. 

Create a Feature Page for the Quizzes

Let's begin by creating the following sections on the quiz feature page and then fill them in. To create sections you can use Headings. I’m using Headings 2. 

First, create the following sections:

• Quiz Feature 

• Background

• Screenshot

• User Stories

• Links

Next, add a general text description of the feature to the Background section. This is a good place to write a few sentences about the context and explain briefly what the feature is and what you need to do.

A picture can tell a thousand words, so we’ll put one or two images in the screenshots section.

The next step is to create a table in the user story section. We’ll add one user story per row and four columns for the ID, User Story, Link and Status.

The tables are quite similar to tables in Word or Google Doc. You can add rows and columns by clicking above the column as shown in the screenshot. You can also add a title to the table if you'd like.

When you've finished filling in your user stories the end result should look something like this:

The user stories section is the most important, especially the link to each individual story's wiki page.

For corporate or product documentation, there are typically some existing related wiki pages that may be useful to link to. Use the shortcut CMD+K or write “/link” to insert a link. You can even add a section for links so that you can add references and related material.

And that’s it! We have the bare bones of a wiki page. Ready to try it out on your own?

Your Turn!

You’re going to create your own Confluence page showing user stories about the pass/fail logic of the quiz. We’ve already taken a look at this in the first part of the course, but if you need another look you’ll find the user stories here. Use the steps we saw in this chapter to add the information to your wiki:

• First, create your  sections 

• Add a background section and fill in the context

• Format the text into Heading 1, Heading 2, paragraph, etc. 

• Create tables to present information (put your user stories into a table).

• Insert images (for example screenshots of the quiz…)

• You can even store all relevant documentation including Microsoft PowerPoint slides, Microsoft Word/Excel documents, or PDF documents all in one central place - your wiki! 

Have you finished? Check your work here! 

Let’s Recap!

• Wikis are a great tool to help the team achieve better transparency and understanding of their work.

• Confluence and Notion are very popular wiki platforms in use by many organizations.

• Wikis are a good way to help document your work.

Now that you have created your own wikis, you're ready to create the perfect user stories. So let’s get to it in the next chapter!