Software Best Practices

I am trying to understand technical software specifications. My own experience is quite controversial and varied. Overall my impressions are that technical specifications are not well understood and not used much.

1. Identity - what is it?
The technical spec is not the same as the functional spec. Joel Spolsky makes a good distinctionin his Painless Functional Specifications - Part 2: What's a Spec? Is it the same as the non-functional spec or does it include non-functional specs? Is it the same as design, does it include design, or does it preceed or follow design?

2. Author - who writes it?
A business analyst or a product manager specifies the requirements (other people might help with security, usability, quality, and so on.). An interaction designer specifies the interface and the flow of the user interaction with the product. Then what: is it the developer who must write the technical specification, or the architect, or someone else?

3. Need - who uses it?
Is a technical specification needed and who needs it? Developers know what they are doing, so why should they write anything (many of them hate writing non-code anyway)! They can also add comments in the code, so thus they can provide explanations, details, or rationale where needed.

4. Practice - who has done it?
Are there any companies or projects that have successfully used technical specs? Are there any examples of a technical spec used to develop a software program or module and what's the story behind - who wrote it, how many times it was modified, when was it written before or after the code?

Thanks in advance for your thoughts and comments

Regards
Dimiter

Wow, you just hit on one of my soapbox issues so I will attempt to keep it brief.

First, any distinction between Functional specs and Technical specs is purely in the eye of the beholder in my opinion. They are, roughly speaking, the same thing. Or, more correctly, different views of the same thing.

People who try to separate Functional from Technical attempt to invoke the customer as the differentiator of the two specs (as Joel did in your reference). That is, if the customer cares about it, it is Functional. If only the developers care about it, it is Technical. I call this in my requirements seminar the “They/We” model. If “they” say it, it is a requirement and it is functional. If “we” say it, it is design and it is technical.

In reality, they are talking about the same thing: the physical design of the system; maybe at different levels of abstraction.

If you buy what I am selling, then your four questions become arbitrary decisions of the organization and something of endless debates. There is no right answer and there can not be one. However, you can drink a lot of beer while arguing over it.

Identity: More detail of the choices made in designing the system. Often at a lower level but sometimes at a higher level when it wasn’t covered in the other spec.

Author: The next folks in the development chain whoever they may be. However, the next folks will grip since the earlier folks made lots of design decisions that may have been better left until the technical folks got to it.

Need: Whoever wants to write code. You got to figure this stuff out at some time. XP does it as it sits at the keyboard. Same decisions have to be made and reviewed. Pair programming does real-time reviews.

Practice: I see a lot of clients try this route and all of them are in the midst of religious wars. So, why wait, join the fun.

BTW: I solve the “They/We” problem by calling it a bankrupt approach and going to the older and wiser approach of “Spaces”. You can see my write about it several times in my blog and other places in the forums.