• 10 hours
  • Medium

Free online content available in this course.

course.header.alt.is_video

course.header.alt.is_certifying

Got it!

Last updated on 11/9/21

Create the Ideal User Story Wiki Page

Log in or subscribe for free to enjoy all this course has to offer!

As you saw in the last chapter, we often build features that break down into a set of user stories. We created the Feature wiki page (for a feature called Quiz), and we'll make the User Story wiki page in this chapter. They are quite similar in terms of the format.

You will recall that we created a table of user stories on our Quiz wiki page.

Our Feature wiki page had a list of User Stories and links
Our Feature wiki page had a list of user stories and links

Let's create a User Story wiki page for the Retake Quiz user story.

Format of a User Story Page

An ideal User Story page has the following sections:

  1. Background 

  2. Screenshots

  3. Acceptance tests

  4. Additional links (if any)

Let's create this wiki page for the Retake Quiz user story, which is as follows:

As a student who failed the test, I want to be able to retake this quiz 24 hours later. 

Background

The background should give a little general information about this user story. For example, the background section for the feature had a high-level description of a quiz. Now, the background section for Retake Quiz should provide a high-level description for retaking a quiz. Here is an example:

A 70% score is required to pass a quiz. Students could fail a quiz.

Those who fail should go back to the course to study it further before trying again.

Therefore, they cannot retake the quiz for 24 hours. If they fail a second time, then they cannot do the quiz again.

Certificates will only be given to students who complete all quizzes and activities, meaning that this student can no longer pass this course.

Screenshots

The Feature wiki page provided a couple of screenshots of a quiz's appearance. But for the user story, you want to provide all the screenshots necessary for this user story. For example, Retake Quiz could have screenshots for:

  1. A student passes a quiz.

  2. A student fails a quiz (within the last 24 hours).

  3. A student fails a quiz (over 24h ago).

Three screenshots with a brief explanation
Screenshots make the requirement easier to visualize

Acceptance Tests

The acceptance tests should be listed here in a table (or several tables depending on how you group them). You can group them by rule as you saw in the chapter on acceptance tests.

Here is an acceptance tests table for Retake Quiz:

Acceptance Tests for the 'Retake Quiz' user story
Acceptance tests for the Retake Quiz user story

Reformatting User Stories

Sometimes, you realize that it would be better to add or remove a user story as you write out acceptance tests.

If the acceptance tests for one story seem to overlap a lot with that of another user story, you may want to merge them (requiring a slight rewrite).

According to the INVEST model, user stories should be independent. However, sometimes you realize that everything would be cleaner if you add/remove a user story or two when writing acceptance tests.

Let's look at that scenario in the next chapter.

Let’s Recap!

  • Wikis are a great place to capture essential user story items such as background, screenshots, acceptance tests, and additional links.

  • Having a wiki site for each level of the classification (PBIs, features, and epics) may help a team see the value in their work.

  • If you use a wiki to organize key decisions, problems, and related items, you can help a team improve by:

    1. Increased collaboration.

    2. Less time creating documentation.

    3. Easier to update documentation. 

    4. Collaboration and transparency improve when using a wiki for documentation.

Our user stories are done, but we will need to add and remove some. Let’s see how to do that in the next chapter.

Example of certificate of achievement
Example of certificate of achievement