Should I be attaching diagrams, wire frames and other design artifacts to User Stories in an agile approach?

Question

I'm just starting to put software design principles and agile into practice. I'm taking baby steps and so far I've started implementing the following for my software projects...

• A github project board with github issues acting as my User Stories.

I'm under the understanding that a huge SRS isn't necessary, but I'd like to know if it's a good practice to just attach any diagrams I feel necessary for the particular story to the issue and NOT create a Software Requirement Specification document.

Also, if it's practical to have a SRS document in agile, what important artifacts might I include?

Answer 1

YOUR TEAM must know what is good for YOUR TEAM

The amount of detail the user tasks should have are team dependent. In that sense, it is not possible to know if for YOUR TEAM it will be good to attach such artifacts or not.

• For teams that are starting to get used to working with user stories, having to always attach artifacts to stories would just create more overhead for a process that is already quite difficult to execute properly (agile).

• For teams that are used to that process and perhaps that have a dedicated Product Owner (or equivalent), this could perhaps be necessary to specify stories and delegates tasks to other teams.

Also, how you document requirements (whether if it is through post-its, a big software requirement specification, attachments on a board, attachments on an email, power point presentations) can and should be what works best for your team.

Following the agile mindset:

Try it.

Measure it.

Does it improve your workflow?

No? Drop it.

Answer 2

Some additional thoughts beyond Albuquerque's answer, which I fully support:

• Drafting an SRS is one way to capture the requirements. Unfortunately it requires to think about all the requirements upfront, at a moment the analyst may not have a full understanding of the domain, and the user don't yet get what the system can/will do for him/her nor what the impacts will be. Misunderstandings and missed opportunities guaranteed!
• User stories are another way to capture the requirements. The agile way. If you have user stories, you don't need the SRS.
• A user story is only a placeholder for a conversation (3C principle) that will elicit the requirements together with the user and interactively. A kind of collective intelligence.
• If you hold this conversation with the support of wireframes or other artefacts, it would be a pity to throw them away and forget about the expectations! So you can attach anything you think is useful to implement the story. If you discussed with your peers and have sketched some rough design on a napkin, take a photo and attach it too. Anything, provided you do not waste your time with artefacts nobody is interested in.

The main difference to keep in mind is that:

• the SRS covers many (theoretically: all) user stories, but is written when nobody had a clear picture of what is really needed,
• the user stories are written just in time. They therewith benefit from the accumulated knowledge of what is needed and of what the software looks like. In other words, it's a knowledge building instrument.

This being said, there are cases where the SRS is mandatory: in some regulated industries, or in public procurement, it can be a legal requirement. Large corporations can mandate it in their internal rules. Two cases may then happen:

• you receive an SRS from the customer at the beginning of the project. It can then help to identify the main stories. But this shall not prevent you from building your system the agile way, interactively with the users.
• you have to produce an SRS as mandatory deliverable. In this case, do not do not write an SRS for each story. Produce the SRS based on the stories (so you'll have to write some introductory sections about the overall system, etc..., but replace the list of functional requirements or the use cases, with your user stories).