Writing Technical Requirements

Who should write requirements? Everyone!

Some of us developers feel a business analyst, project manager, or tech lead should write technical documentation. I'm here to tell you that it's not explicitly their job! We need to be part of writing them. In fact, the more stakeholders involved with writing requirements, the less chance of things slipping through the cracks in the development cycle.

I found that at Vodori, while the people I worked with were brilliant beyond measure, not all of them were comfortable writing markup requirements related to CSS styling. This resulted in vague requirements that would force a developer to stop their workflow to ask questions. This also led to missing implicit requirements. Again, this is not their fault. We should have all participated in the exercise!

What do good requirements look like?

Take link styling as an example. It's much more than just the color of the link. Here's an example of a complete set of styling requirements for links. These requirements outline context, colors, states, decoration, and nuance.

These requirements are for links inside of body copy. Links within other areas have a different set of requirements.

• The active state should have no text-decoration.
• The active state should be the color: #4196b4.
• The hover state should have an underline.
• The hover state should be the color: #365d9d.
• The visited state should have an underline.
• The visited state should be the color: #5e4d62.
• The text size of links in all states should always be the same size as the paragraph it is contained within.
• All links within paragraphs should open within a new tab unless otherwise noted.
• Links should have the same font-weight as the paragraph: normal.
• On Safari iOS7 and iOS8, the tap state should be removed.
• On Safari iOS7 and iOS8, the visited, and active state should be visible.

We have to write requirements sooner or later

We have to address the requirements for all of these components at some point. I argue that the development cycle goes faster and smoother when we provide requirements in as much detail as possible before development begins, than to piece-meal it on the fly later on. If we spend the time up front writing detailed requirements, it results in:

1. Less bugs
2. Less back and forth between developers and QA analysts
3. Faster development (developers work faster with things spelled out)
4. Less ambiguity around decisions (the requirements are requirements for a reason!)
5. Higher quality output (with the edge cases covered in the requirements, the quality of the code will be higher)

Of course, we can't always capture everything in the requirements. There will always be some degree of improvisation in resolving bugs. However, the more detailed we can be up front, the better off we will be as we progress in the development cycle.