Technical Spec: Is more detail help or hindrance?

Question

When writing a full Technical Spec - defining in details what every part of the system will do, show and look like - does it help to state the obvious?

Let's take the easiest example:

A Login Screen needs fields for username & password and their limitations. Those details need to be described.

But (assuming you've never done this before and can't copy from another spec) does it suffice to say: Include "lost password link" and assume the engineers are mature enough to know what to do.

Or should it go into the details of what happens when you click on that link, what the text of each stage says and what the arbitrary timeout limits are?

Or should it say "...and behave like ____________ does, and a pointer to some other product?

Would there be any advantage to writing 2 - 3 pages with all the details, or will this type of detail be counter-productive, similar to micro-management?

Answer 1

This really depends on how you and your collaborators like/are expected to work, how much time you want to invest in getting things right, and how painful it is for you to not have some of the detail realized.

If you want to define something once, look to have one delivery, and expect everything to work 100% according to your own understanding, then you would probably want to break things down to that level of detail and make sure everyone involved can work with it.

If you are planning for a couple of iterations on your deliverable, then you could simply break down your detailed requirements into chunks and revisit those that do not work as you expect them to (without having defined explixit requirements). In this case, you will probably want to make sure that your collaborators are happy to go along with that approach (risk of your always aksing for too much "more"). The risk here is that the team can never really anticipate when it will be done.

The hybrid approach would be to define a high-level set of requirements and add your detailed expectations as a kind of reference/appendix. In this case, you would probably rely on the "maturity" of your engineers without being able to control the outcome (both of you will accept the respective others' perspective). And yet, for anyone caring enough about what you want to see in the product, they could at least skim those details and adjust their take on the high-level requirements accordingly. Again, an option with compromises to be made, but with some prospect of your expectations being met in their entirety.

Answer 2

Document the minimum required for a proper, unambiguous implementation.

It requires a lot of efforts from both analysts and implementors, so will depend a lot on your project environment maturity.

If you're working on a more agile environment, a close relationship and conversation between parts might reduce the amount of extended documentation.

If you're working on a more contractual, waterfall oriented you may need to have a more detailed documentation. To avoid a lot of repetition of text, you may consider to include or extend such requirements as part of your use cases. Another example here.

Answer 3

There are different approaches to the lifecycle of a project which are often described as ranging from "predictive" (define everything early and as fully as you reasonably can) to "adaptive" (define everything as late as you reasonably can).

A lot depends on a team's ways of working but relying on evidence-based results rather than detailed specification often makes better use of a team's collective problem-solving ability. Let the team determine how much detail they need. Ultimately any technical spec ought to take second place to validation, testing and customer feedback.

During contract negotiation being more predictive about the details means the vendor takes on a greater share of the delivery risk while the purchaser takes a greater share of the cost and risk of unforeseen changes in requirements. A more adaptive ("agile") approach assumes requirements aren't fully known at the start and will naturally emerge during the course of the work. Improved control of cost and risk are often cited as one of the reasons for taking an agile approach in software development.

Answer 4

Is more detail help or hindrance?

More detail helps until it becomes a hindrance :). In other words, the law of diminishing returns starts to apply at some point. Your developers will find some details useful while others will just state the obvious. And you will need to keep these details up to date which might involve quite an effort and cause a waste if you always need to make changes in writing to things that are obvious.

Of course, finding the right balance point is hard to do. You don't know upfront what will be needed to be specified and what can be left to people's experience. Using your example, the login page should be something anyone understands how it works, what security constraints apply, how password reset will work, etc. So at first look, not much detail seems to be needed. But things can be forgotten (like the need to include a "Forgot password" link) or things can be open to interpretation (for example, I've seen very often cases when the programmers didn't shy away from storing passwords in plain text in the database; in this case, a more detailed spec constraining the way the passwords need to be stored is needed).

One option is to ask the team how they want to receive their requirements and what they should contain. Start from there, then inspect the result and see what issues come up, which will be an indication on how much needs to be defined upfront, and how much you can count on the developer's experience to fill in the gaps.