Menu
As any experienced product owner, business analyst, or project manager knows, product definition can be an arduous process. Finalizing product details, prioritizing what needs to be completed, even relaying the specifications to the development team all takes time. The question is, how can all of this be done without compromising timelines? Or worse, having your project become a nightmare to manage? From what I have learned this comes down to the “simple” task of proper product documentation.
Working in an agile environment for a while now, I have come across and used two different methods of product documentation: stories and specification documents. They both have their benefits, but like all methods of doing anything, leave something to be desired.
In agile software development, stories define small pieces of functionality (e.g. Clicking a button to perform an action) that can be completed and combined to comprise a larger function or portion of software called an epic. All epics combined are the complete software.
Written properly, stories should convey any information about the task that needs to be completed so the developers know what they need to do. As well, they should contain any acceptance criteria that the product validation or quality assurance team members can use to qualify that, yes, this functionality has been completed properly. All the while, the creator of the stories must keep this information as concise and granular as possible to avoid confusion for anyone else reading them. Finding the right balance of information is tricky but paramount to the success of using stories. In some cases, stories prove difficult to use due to the lack of context in the large scale of the project.
There are tools out there to help make story creation and organization easier, like JIRA, Rally, and Trello. These tools provide methods to create stories and the ability to add subtasks to each of these stories if desired. Swimlanes (a term used to describe the organizational status of a story) are also present to allow project managers to move stories into and out of sprints to more clearly define the work needed to be done. Although these tools have proven useful for organization in many projects done here at Clearbridge Mobile, creating or modifying stories within them can prove time-intensive, particularly when many alterations need to be made.
The alternative to using stories is the specification document or spec. doc., as it is commonly referred to. The spec. doc. is a detailed collection of the software’s functionality. It is regularly written using bullet points but can take any form as long as it covers every detail of every function, from error messages to character limits.
Since it is just a document, the spec. doc. doesn’t require any special tools. I personally use Google Docs, but any word editor will suffice. With no extra logins or tool navigation required, modifying the document typically takes less time than modifying a story. I have also found that, because everything is in one document and not spread out into different stories, the full context of an action and how it affects the user experience is simpler to ascertain.
With that said, spec. docs. do have their drawbacks. Modifying the document may be easier; however, conveying what has been modified to the developers can be difficult since there is no status. Making time-stamped comments on the side of the page or highlighting the updated information can only go so far and requirements can be lost in translation.
I performed a quick survey of developers, QA, project managers, and product owners on what they would prefer: stories or the spec. doc. The survey also provided the options of both, none, and other, where those surveyed could provide their own preferred method. Of those that responded:
From the results there is one consistent conclusion that can be made: preferred documentation is very much dependent on job function. Due to the organizational nature of PM roles, having the structure of stories is very beneficial. Development appreciates the granularity that stories provide, allowing them to focus on one problem at a time. And, contrary to developers, QA finds that testing with the whole context of the software in mind creates better tests; thus, the spec. doc. is more useful to them. However, all these stats provide are the ability for us to create generalizations. No one method is unanimously preferred.
What is conclusive is that proper product documentation – whatever form it may take – is crucial to the success of any project. In the end, the best decision may be to know what will benefit your team the most and help them produce the best work. So for your next project, before you get started writing your requirements, really sit and think about it: Stories or Spec. Doc.?
Clearbridge Mobile is an award-winning, full-stack mobile app development company dedicated to helping companies strategize, develop, and scale dynamic mobile app solutions that enhance business performance and enable innovative growth opportunities.
