The 4 Reasons Why User Stories are Better than Requirements Specifications

In this post I’m going to show you why User Stories are a better solution than Requirements Specifications to effectively understand user needs and build successful products.

Introduction

Software requirements is a communication problem.

How do you decide what a software system is supposed to do?
How do you communicate that decision between the various people affected?

communication_problem

Experience has taught us that Requirements Specifications do not work anymore in today’s  world and that User Stories are a much better solution.

I’m going to explain you why in this post…

What are Requirements Specifications?

A typical Requirements Specifications fragment is the following:

IEEEFormat

There is a tremendous appeal to the idea that we can think about a system and then write all the requirements upfront.

Requirements Specifications written like that have sent many projects astray because they focus attention on a checklist of requirements rather than user goals.

What Is a User Story?

A user story describes functionality that will be valuable to either a user (who uses the system) or customer (who pays for the system).

user_story

The format of a User Story is the following

As a <Role> I want <Function> so that <Benefit>

as in the example below

As an executive, I want to generate a report so that I can understand which departments need to improve their productivity

Our goal with user stories is to write down a short place holding sentence that will remind developers and customers to hold future conversations.

Why User Stories are better?

1. Comprehension

A way that extensive upfront Requirements Specifications can kill a project is through the inaccuracies of written language.

The shift toward verbal communication of User Stories provides rapid feedback cycles, which leads to greater understanding.

2. Planning

A difference between User Stories and Requirements Specifications is that with the latter the cost of each requirement is not made visible until all the requirements are written down.

With stories, an estimate is associated with each one right up front so that they may be conveniently used for release planning.

3. Resiliency

Change always happens in projects…

  • Users and customers do not generally know exactly what they want
  • Many of the details needed to develop the software become clear only as the system is being developed
  • Product and project changes occur
  • People make mistakes

User Stories embrace change because

  • Do not need to be all written before developers can begin coding the first
  • Encourage deferring details because we can write them at whatever level of detail is appropriate in a given moment.

4. Prioritization

It’s hard to prioritize and work with thousands of sentences all starting with “The system shall…”.
That difficulty usually results in having the user considering 95% of the requirements high priority!

On the opposite, User Stories can be easily ordered by priority.

References

Mike Cohn

How to Create a List Item Inside a Folder Using a SharePoint Designer 2013 Workflow

In this post I’m going to show you how to create a list item inside a folder in a SharePoint Designer 2013 workflow even though the “Create List Item” built-in action and even the new rest api do not allow us to do that.

Scenario

We have a folder inside a custom list and we need to automatically create items inside it using a SharePoint Designer 2013 workflow.

Item in Folder- Folder

Problem

In a SharePoint 2010 workflow we used to simply set the “Folder” property in the built-in action “Create List Item”… and it worked! Our item was correctly created inside the specified folder.  Unfortunately in a SharePoint 2013 workflow setting the “Folder” property has no effect. Even the new SharePoint 2013 rest api does not come to our rescue.

Solution

We can use the old listdata.svc service to achieve our goal making a rest call to it inside our SharePoint Designer 2013 workflow.

Steps

1. Create the headers dictionary

We must build a dictionary to store some headers, specifically the following ones:

Accept: application/json;odata=verbose
Content-Type: application/json;odata=verbose

Item in Folder- Headers.png

2. Create the data dictionary

Next, we need a dictionary that will contain our request data.

The dictionary must have an entry for each item mandatory fields and an entry to set the item path.

Title: Item 1
Path: <list url>/Folder 1

Item in Folder- Data

The item path must be constructed dynamically to point to the folder we want to place our item in.

Item in Folder- Path

3. Call the SharePoint REST service

Finally, we are ready to call the SharePoint REST service to create our item inside the list folder.

To do this we need to insert the “Call HTTP Web Service” action in our workflow.
The action url must be constructed dynamically like this:

https://site/_vti_bin/listdata.svc/SimpleList

Item in Folder- Endpoint.png

The http method must be set to POST.

Item in Folder- Method

The request headers must be set to the headers dictionary.
The request content must be set to the data dictionary.

create_list_folder10

Conclusion

This is how the complete workflow should look like:

Item in Folder - Workflow

Now we can publish and run it and see that a new item is correctly created inside our folder.

Item in Folder- Folder Workflow Completed

Item in Folder- Item Workflow Completed

References

MSDN

How to Approve a List Item Using a SharePoint Designer 2013 Workflow

In this post I’m going to show you how to approve a list item in a SharePoint Designer 2013 workflow even though the “Set Content Approval Status” built-in action is no longer available in SharePoint 2013 On-Premises.

Note: the issue this post is about has been solved in Sharepoint 2013 Online (Office 365).

Scenario

We have a custom list that requires content approval for submitted items and we need to automatically approve them when they are created using a SharePoint Designer 2013 workflow.

ApprovalList

Problem

It seems quite simple, like in a SharePoint 2010 workflow there should be a built-in action to do this… but unfortunately this is not the case. In a SharePoint Designer 2013 workflow there is no such action as the old and dear “Set Content Approval Status”.

So we need to find a different way to achive the same result and as always with SharePoint 2013, the REST API comes to our rescue.

Solution

We can use the SharePoint REST API to update a list item and set its approval status.

Now we only need to know which particular property of the item sets its approval status…
We can find that by inspecting the item properties through a rest call via a browser like this:

https://site/_api/web/lists/getbytitle('listname')/items(ID)

ApprovalStatusProperty
You can see that the only property that could do our job is the one called “OData__ModerationStatus” (note the double underscore before the “ModerationStatus” string).

The possibile values for this property are the following:

  • Approved: 0
  • Rejected: 1
  • Pending: 2

So now we need to update this field.

Let’s see how to do that in detail…

Steps

1. Get the list item type

To get the list item type we need to use the SharePoint REST API via a browser like this:

https://site/_api/web/lists/getbytitle('listtitle')

and get the value for the “d:ListItemEntityTypeFullName” element.

In the example below the list item type is “SP.Data.Test_x0020_ListListItem” (the “_x0020_” string replaces the space inside the list name).

ApprovalListItemType

2. Create the headers dictionary

We must build a dictionary to store some headers, specifically the following ones:

Accept: application/json;odata=verbose
Content-Type: application/json;odata=verbose
Content-Length: <length of post body>
X-HTTP-Method: MERGE
If-Match: *

create_list_folder5

3. Create the metadata dictionary

Next we need to create a dictionary to store our metadata.
This dictionary will contain only one entry for the list item type we’ve obtained previously:

type: SP.Data.Test_x0020_ListListItem

ApprovalMetadata.png

4. Create the data dictionary

Next, we need one more dictionary that will contain our request data.

The dictionary must have an entry with key “__metadata” (note the double underscore before the “metadata” string) with its value set to the previously created metadata dictionary.

We also need to add another entry in the data dictionary with its key set to “OData__ModerationStatus” and its value set to 0 (Approved).

__metadata: <metadata dictionary>
 OData__ModerationStatus: 0

ApprovalData

5. Call the SharePoint REST service

Finally, we are ready to call the SharePoint REST service to update our item approval status.

To do this we need to insert the “Call HTTP Web Service” action in our workflow.
Put it inside an App Step to make sure the REST call is executed with elevated privileges.

To see how to enable the use of App Steps in your workflow and give it elevated privileges see this article.
To see pending items in the same web of the workflow you need to follow the above procedure with Scope=”http://sharepoint/content/sitecollection/web”.
To see pending items in the same site collection of the workflow but in a different web you need to follow the above procedure with Scope=”http://sharepoint/content/sitecollection”.

The action url must be constructed dynamically to point to the current item like this:

https://site/_api/web/lists/getbytitle('listtitle')/items(n)

ApprovalEndpoint

The action verb must be set to POST.

create_list_folder9

Set the request headers to the headers dictionary.
Set the request content to the data dictionary.

create_list_folder10

6. Change workflow default settings

At this point it is very very important to uncheck the “Automatically update the workflow status to the current stage name” option, otherwise during the workflow execution the item will be updated and its approval status reset to “Pending”.

We also set our workflow to start automatically when an item is created.

ApprovalWorkflowSettings

Conclusion

This is how the complete workflow should look like:

ApprovalWorkflow

Now we can publish it and see that when we create a new item the workflow will start automatically and correctly approve it.

ApprovalItem

References

MSDN

StackOverflow

How to Create a Folder in a SharePoint 2013 List Using a SharePoint Designer 2013 Workflow

In this post I’m going to show you a workaround to an issue with SharePoint Designer 2013 workflows in correctly creating a list folder.

Scenario

We have a custom list and we need to dynamically add folders to it through a SharePoint Designer 2013 workflow.

create_list_folder12

Why

A first question could be:

Why on earth would you need to create a folder in a list? Folders are intended for libraries and files!

There are scenarios when you need to have folders in your list, one of this is to manage permissions at a finer level than the list level, avoiding having to set unique permissions for each list item.

A second question could be:

Why on earth do you need to create folders with a workflow?

There could be scenarios in which folders need to be created dynamically in reaction to some event.

Problem

A list folder is simply a special type of list item.
So it seems quite simple… In the workflow use the “Create List Item” action and set its content type to “Folder”. Yes, it works! The folder is created!

But wait… Clicking on the folder an ugly system name appears in the breadcrumbs (ID_.000)… Oh no! What’s that?!?

create_list_folder2

This happens because there is a mismatch between the title of the folder that we can set in the workflow and its name that is assigned automatically (respectively “Folder 1” and “66_.000” in the example above).

Unfortunately we can’t set the name of a list folder directly using the create or update list item workflow actions.

Solution

We can use the SharePoint REST API to change the list folder name after having created it.

Now we only need to know which particular property of the list folder sets its name…
We can find that by inspecting the folder properties through a rest call via a browser like this:

https://site/_api/web/lists/getbytitle('listname')/items(ID)/FieldValuesAsText

create_list_folder3
You can see that value “ID_.000” is hold by the field “FileLeafRef”.
So now we need to update this field of our newly created folder using REST.

Let’s see how to do that in detail…

Steps

1. Get the list item type

To get the list item type we need to use the SharePoint REST API via a browser like this:

https://site/_api/web/lists/getbytitle('listtitle')

and get the value for the “d:ListItemEntityTypeFullName” element.
In the example below the list item type is “SP.Data.TestFolderListListItem”

create_list_folder4

2. Create the headers dictionary

We must build a dictionary to store some headers, specifically the following ones:

Accept: application/json;odata=verbose
Content-Type: application/json;odata=verbose
Content-Length: <length of post body>
X-HTTP-Method: MERGE
If-Match: *

create_list_folder5

3. Create the metadata dictionary

Next we need to create a dictionary to store our metadata.
This dictionary will contain only one entry for the list item type we’ve obtained previously:

type: SP.Data.TestFolderListListItem

create_list_folder6

4. Create the data dictionary

Next, we need one more dictionary that will contain our request data.

The dictionary must have an entry with key “__metadata” (note the double underscore before the “metadata” string) with its value set to the previously created metadata dictionary.

We also need to add another entry in the data dictionary with its key set to “FileLeafRef”.

__metadata: <metadata dictionary>
 FileLeafRef: Folder 1

create_list_folder7

5. Call the SharePoint REST service

Finally, we are ready to call the SharePoint REST service to update our folder name field.
To do this we need to insert the “Call HTTP Web Service” action in our workflow.
The action url must be constructed dynamically to point to the newly created folder like this:

https://site/_api/web/lists/getbytitle('listtitle')/items(n)

create_list_folder8

The action verb must be set to POST.

create_list_folder9

Set the request headers to the headers dictionary.
Set the request content to the data dictionary.

create_list_folder10

Conclusion

This is how the complete workflow should look like:

create_list_folder11

Now we can publish our workflow and run it. Once it is over we’ll have our folder correctly created with its title and name matching.

create_list_folder12

create_list_folder13

References

StackExchange

The 4 Principles of an Effective Work Breakdown Structure

In this post I’m going to show you how to create a Work Breakdown Structure as the foundation for your project planning.

Definition

A Work Breakdown Structure (WBS) is a simple, yet methodical way of organizing a project scope in a hierarchy of smaller and manageable components and is the foundation of project planning.

pyramid

Why

So, why bother creating a WBS for your project?
Hereafter a few reasons…

  • Gives clarity on the project needs in terms of deliverables and success criteria – it highlights the “what” of the project
  • Subdivides the scope into manageable components in terms of size, duration, and responsibility
  • Aids in monitoring and controlling the project

question

Principles

  1. 100% Rule: The WBS should define the total scope of the project and capture ALL deliverables, including project management. If not, the risk of gaps and missing components is high.
  2. Mutual Exclusivity: It is important that there is no overlap in scope definition between two elements of a WBS. This ambiguity could result in duplicated work.
  3. Deliverables, Not Actions: Deliverables are the desired ends of the project, such as a product, result, or service and can be predicted accurately. Actions, on the other hand, may be difficult to predict accurately.
  4. Reasonable Level of Detail: Don’t go into too much detail. What you’re looking for is enough detail so you can plan, manage and control the project. An effective limit of WBS granularity may be reached when it is no longer possible to define deliverables and the only details remaining are actions. The lowest level in the WBS is called a “Work Package”.

principles

Process

  1. List high-level deliverables
  2. Get granular
  3. Check WBS principles

process

Example

In the following image you can see an ideal Work Breakdown Structure.

example

Agile

WBS applies also to Agile. An agile WBS is organized around end-user deliverables. Here deliverables are decomposed into Epics, User Stories and Functionalities.

agile

How to Design Better and Faster with Rapid Prototyping

In this post I’m going to show you how to use low-fidelity prototypes to gather and analyze requirements and get users actively involved in the process.

Introduction

A picture speaks a thousand words

The majority of us prefer visual communication compared to reading lots and lots of fine print. The former method is fun and immersive, the latter requires total concentration and is painful to many.

prototype_brain.png

These concepts capture better that anything else what user interface prototyping is all about:

Using visuals to describe verbose software requirements and specifications that detail how a system should behave and look

Process

Rapid Prototyping is the process of quickly mocking up the system to build and validating it with users, stakeholders, developers and designers.

Doing this rapidly and iteratively generates feedback early and often, improving the final design and reducing the need for expensive changes during development.

prototype_process.png

Advantages

  • Increased user involvement. Prototyping requires user involvement and let them see and interact with the system before it is built allowing better and more complete feedback and specifications
  • Early testing. Errors, usability issues and missing functionality can be detected earlier in the process
  • Criticality detection. Confusing or difficult functionalities can be identified easily
  • Increased clarity. Ambiguity and misinterpretation are reduced
  • Reduced cost for changes. Because changes cost exponentially more to implement as they are detected later in development, the early determination of what the user really wants can result in less expensive software

prototype_advantages.png

Dos

  • Prototype only those features or functionality that can be implemented. When in doubt, confirm with developers before starting
  • Begin prototype review sessions with clear guidelines for feedback. Be very specific about the type of feedback you are looking for (Are the steps logically arranged? Is the navigation clear and intuitive?)

Fidelity

Fidelity refers to how closely a prototype resembles the final solution.

There are multiple dimensions of fidelity (Visual, Functional and Content), and prototypes can lie anywhere on the spectrum for each of these dimensions.

prototype_fidelity.png

My advice is to build prototypes with low-fidelity for visual and content dimensions, and high-fidelity for the functional one (interactivity). In that way users can focus on the functional aspects of the system and are not distracted by its look and feel.

Indeed, high visual and content fidelity can sidetrack prototype reviews. Rather than telling you about navigation and interactivity users will start focusing on colors, fonts etc. which is not appropriate in early stages of the design process.

Tools

Depending on your approach, you have a wide variety of tools to choose from.

A really interesting low-fidelity prototyping tool is Balsamiq. This tool lets you quickly mockup a design by dragging and dropping common interface elements onto a layout.

Balsamiq prototypes can encapsulate nearly everything – full screen transitions, modal views, status/error messages and so on. No programming skills are required and different templates and building blocks are available.

You will be surprised how quick and inexpensive it can be to produce a representational prototype with this tool.

Here below you can see a screenshot of a prototype I’ve built with Balsamiq for one of my clients using the SharePoint 2013 template.

prototype_mockup.png

References

Lyndon Cerejo

Andrew Chen