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?


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.

| improve this answer | |

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.

| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.