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.

 Earl,

Can you provide more details about the seminar you mention?  I'm new to the site.  So I'm not familiar with your work.

I believe there should be a clear separation of technical spec from functional spec.  Here are a few reasons:

1)  Functional analysts have a critical job and can't be expected to know technical patterns and technical modeling techniques.  They need to be skilled at authoring use cases, business rules, and the various levels of requirements, plus the management of all those artifacts.  When was the last time you heard a developer say, "Wow!  You included everything I need to know in this spec.  I'll get to work now with the technical stuff."?  Not often.  That's because, whatever the current level of skill for a particular functional analyst, they still need to learn these techniques, plus the problem domain!

2)  Techies can't do all of the above because they are busy writing ER diagrams, class diagrams, object diagrams, data flow diagrams etc.  Plus, they don't want to talk to the customers and the customers don't want to talk to them.

3)  Approvals need to be made.  Functional specs need to be approved by both technical and functional leads, as well as the customer (in some distilled form).  

4) Consumers of functional specs include more than just the developers.  The testers need it.  IA, QA, CM, and perhaps even PMO need to review them when things go wrong.  Trainers need it to write training modules.

5)  Tech specs need to include technical requirements.  Technical requirements may not come directly from the customer, but are authored by senior technical leads (e.g. architect), as an interpretation of the behavior the customer will need. 

I agree that there is a certain amount of cross-over.  But without lines chaos ensues, especially on a large team working on a large system.

Thanks,

Brian

Hi, Brian, welcome to Construx Conversations!

The class I referred to is Construx's Requirements Boot Camp. I agree with you that what can be in a "Functional" spec and what is in a "Technical" spec can (and perhaps should) be at different levels of abstraction. However, I think they abstracting about the same thing. It is like the difference between a house layout, a blueprint, and the wiring diagram. Different people with different skills build all those things but they are about the same thing. Nothing in them explain WHY they are building it, just that it needs to be built that way.

Because they different levels of abstraction and invoke different tradeoffs/skills, I agree that it may make sense for a clear separation. However, that separation will be a line drawn by the particular organization based on the skill sets of the people and culture, not based on the inherent properties of the content. Different groups will draw different lines. I worked with a team where the VP of Product Marketing was a world-class interface designer. Guess what his specs included? Right, highly detailed user interface designs. The right call for him. The product marketing people who worked for him tried to do the same thing since the boss did it and theirs were a total mess. The company solved this by moving the VP himself back into the development organization.

Problems-space requirements (the classic "what" not "how") are seldom in "functional" specs as they are typically about the "how". Why do we have a use case or a business rule? Because we want to achieve something and this is the way figured out HOW to do it.

I recently attended a class from Pragmatic Marketing which I blogged about where they teach Product Manager how to write requirements without talking about the "how". Now to my ears, that is what a lot of folks have been trying to say are "real requirements".

There are also a lot of people who say, "if 'they' require it of you, then it is a requirement" and the analyst job is to help determine if they really mean it. My experience suggests that when "they" require it of you, they are choosing a solution, a "how", not describing the problem they want solved.