Writing Software Specifications In An Agile World
Ways to adapt your specification writing skills in Agile.
Writing functional specifications for a business analyst (BA) in an agile setup is a challenge of a different kind. You no longer have the luxury of time (unlike bigger waterfall projects). You no longer can be sure with a specification version as the final document (because of the iterative philosophy). You are not sure how comprehensive the functional specification should be (Agile manifesto: working software over comprehensive documentation).
Hold on ! Before moving ahead, lets clearly define the scope and need for a ‘functional specification document’ in agile.
Enterprise IT organizations with long term complex projects— While moving from waterfall to agile model, they still had to maintain traditional style of documentation. This was mainly to facilitate the process of sign-offs as most clients still expected the old way of creating requirement/solution documents — for compliance purposes. It was normally difficult to achieve client sign-off on the typical agile artifact like a user story or a acceptance criteria. Also, it is cumbersome to document all the underlying functional and architectural justifications on a light agile artifact. Even for a Product based organization — maintaining all the implemented features requires a centralized document commonly known as product specifications.
Thus there was a need for a document in MS-Word, Google Sheets or on one of the collaboration software like sharepoint, confluence etc. They contain detailed requirements, business context, in-scope/out-of-scope items and generally be more verbose. These documents provide traceability to a user story (SCRUM), acceptance scenarios (ATDD : Acceptance Test Driven Development) or feature files (BDD : Behavioral Driven Development).
In short, the functional specifications ends up complimenting the prescribed agile artifacts by providing a centralized view.
If you are a BA who has been molded in a waterfall set-up, writing specifications in agile can be quite a change from the usual process. Documenting a feature, change request or a new user interface in agile model requires a perspective which allows for changes or feedback to creep in at a later stage. It also calls for some new ways for dealing with all the moving parts of the agile world.
Let’s look at some of the other typical challenges that are often encountered:
Writing specifications for small chunks of development
Normally in agile mode, a big feature or functionality is broken into smaller parts and development is spread across multiple iterations. This means that in order for a development work unit to get accepted, the BA has to quickly write specifications for that small part and get an agreement over it. This modular way of documentation is a big departure from the traditional way of documentation wherein you can think and dwell over the impacts over all the end-to-end flows.
Writing specifications parallel to ongoing development
This is the problem which brings out the most conflicts amongst team members. The sprint starts and in parallel, the BA is quickly writing specifications while the developers are starting to create the design. In the best-case scenario, the BA passes the specifications to the developer just in time for them to start coding. In the worst-case scenario, the BA gets stuck in cycles of clarification and changes and the developer has to change/modify the code much later once the final confirmation comes. A lot of teams try to bypass this by writing specifications one sprint before development starts. However this problem still occurs frequently when timelines are tight.
Review process for specifications
The review process in agile includes stakeholders like developers (Dev) and testers apart from the usual ones. Since it is a very collaborative development model, the entire team has to own up and question the deliverable. This helps the developers in catching some obvious design mistakes and also gives an opportunity for the QA to design testing strategy at an earlier stage. However this also means more and more walk-through sessions, and more context switch for the team members. If the BA is not able to build consensus during the review process, he/she falls behind the actual development happening in parallel.
Rewriting specifications as per feedback in demo
In agile, the demo is where the fate of the deliverable is decided (if the feature is not already presented to the stakeholders earlier). If the customers are not happy about something, or there is some fine-tuning required, the BA has to go back and change specifications. This means one more round of sign-off. All this eats the bandwidth of the BA and increases more follow-ups.
How verbose should the specifications be?
Agile manifesto values say “working software over comprehensive documentation”. But are organizations really prepared to ditch the huge specifications and opt for leaner ways of writing specifications? Some are and some aren’t. A lot of the industries where compliance plays a big role are hesitant to ditch the old style documents. They recommend writing everything for the aim of the sign-off. A lot of product companies have started embracing lighter documentation style. But the jury is still out on a singular style of documentation. Sometimes in scrum, the BA is unsure about the depth in which he/she should write specifications, so that a) no alternate flows, out of scope points and impacts are missed out and b) it should not take a really long time to write and get a sign-off on the specifications.
Looking at the bright side
Let’s look at some of the brighter side of the documentation work in agile. With the great feedback loop that agile has in place, a BA gets to test their specifications with a wide variety of expertise. You get a chance to build great rapport with the development and the testing team. You also don’t have the pressure of creating a 100-page specification document in one go. The staggered approach gives you time to introspect, react and make changes in time if you have missed something. The idea eventually is to be smarter and more proactive in managing the specifications in agile.
How should we overcome the challenges?
Some of the best practices that I advocate for writing specifications in agile :
- When you write small chunks of specifications in an iterative way, make sure the style and the way of writing are similar and consistent each time.
- Devise a way to make the specifications crisp and compact. If you have just moved to agile, revisit the specification template and create a lean one. Make sure that the BA community in your unit collaborates on this and keep your managers and other stakeholders informed that this will be the new way of writing specifications. Inform them clearly of the pros and cons behind this, so that they are not caught unawares at a later stage.
- Get the specification reviewed early by team members and the Product Owner (PO). Find time to give a walk-through of the specification, preferably a time of their choosing. Even if the specification is in a draft stage, it is always better to share that with the developers and testers. It will at least point them in a broad direction.
- Always decide on a client sign-off date even if it is not possible in the current sprint. Make it a practice to keep a checkpoint for specification sign-off during code promotions to advanced platforms (much before production activation). It is also possible to get separate sign-offs for the different chunks of specifications (although this is almost always very hard to practice). Remember : No matter what, one should never activate a piece of code in production without ensuring the corresponding piece of specification signed off.
- Make sure you factor all the bandwidth required to go back and forth on the specification sign-off. This helps in estimating the time it took for the specifications to be completed in its entirety.
- Always have a clear traceability between the user stories/acceptance criteria/feature files and the specification, between the QA test cases and the specification and between the developer unit tests and the specification. Try to have the specification link in the user story description as early as possible.
The entire idea is to be flexible in the whole process while tying the scope of your project. In the end, a business analyst has to adapt and discover the intrinsic value that agile brings into the quality and correctness of the specification writing process.
How has been your experience in writing functional specifications in agile ?
