The process of writing a technical specification

Question

I'm slightly worried that this may be a duplicate, but I have searched the site and every question that I can find seems to be more focused on functional specifications rather than technical ones.

I'm looking for information on how to communicate how something should be done, rather than what should be done. I think at the simplest level I'm looking for the best way to help explain to junior coders the correct way to implement a functional spec.

Most of the answers regarding documentation seem to assume that once given a detailed list of requirements the developes will know the best possible way to implement it and I tend to find that it often isn't the case. The best resource I've found so far seems to be 10*Software Development by Steve McConnell, but I was wondering if anyone else had some useful answers.

Answer 1

I'm going to suggest reading Joel's series starting with Painless Functional Specifications - Part 1: Why Bother? He even has a link to the Project Aardark specification (now Copilot) that you can download and read as an example of what makes a good specification.

One point though: you mention both technical and functional specifications in your post. There's a difference.

You're touching on the issue of coding standards it seems like (as well).

Personally I favour Wiki based approach for purely technical design documentation. Developers jsut don't like writing large Word documents. Wikis allow you to write stuff, collaborate, insert class diagrams or whatever is appropriate.

I found some more information on this like this thread about technical vs functional specifications where Joel writes:

My way of thinking is that you just don't write "technical specs" that cover the entire functionality of an application ... that's what the functional spec is for. Once you have a complete functional spec the only thing left to document is points of internal architecture and specific algorithms that are (a) entirely invisible (under the covers) and (b) not obvious enough from the functional spec.

So the technical spec winds up not existing. In it's place you may or may not have a few technical articles on small topics:

and

Remember, if anything you're talking about affects the user interface or even the behavior of the thing you're building, it goes in the functional spec... so all that's left for technical specification is things that are SOLELY of interests to programmers, and, in fact, a lot of that stuff might be best in comments, so at most, you should have a handful of short articles on topics like algorithms -- and you write those articles on demand, when you need to think through a design, or document the "big picture" for future programmers so they don't have to figure out what your code is trying to accomplish.

which describes it far more eloquently than I.

Answer 2

Two thoughts:

The most useful way I know to communication about a proposed implementation is to use class diagrams and sequence diagrams.

I think even junior developers should be given the responsibility of creating the initial description. Thinking about the problem space, then receiving a critique of the design, is going to develop their abilities much faster.

Answer 3

You will get a lot of mileage out of augmenting your functional spec with a coding standard, code reviews, and possibly a static analysis tool like FxCop. Code can be based on a reasonable architecture, but become hard to change because of bad style at the local level.

Answer 4

Interesting, I thought this question would get dozens of well argued answers, instead we get suggestions that coding standards will fix the problem or letting the devs get on with it is the answer. From the question, I think the key is that we're talking about junior coders, when you're starting out there's a huge jump from functional spec to finished code, and we all know that there's more than one way to do it.

My approach would be to take a particular part of the system, what exercises all the technical layers - DB, UI, Web services whatever, and document how that should be implemented, maybe using class diagrams, maybe just suggesting the specific libraries and approaches. In this way your tech spec isn't too big, compliments and extends the architecture document (which can be a bullet point list if you don't want too much doco).

The team can then fully implment a vertical slice of the system which has many advantages, you can build and release a small slice early, the architecture is proven, the iteration 0 stuff (source control, versioning, build) is all exercised - it's just the way to do it.

Answer 5

I think this boils down to certain design basics:

• You create a list of requirements or a functional specification
• You look at all possible ways to solve the problem
• You decide which ways fits best or leads to the best result

What you describe shows that they didn't make a good (if any) analysis of the pro's and con's. In the end it comes down to how well the Junior's themselves are able to gather the right information and then make the correct decision. This might involve asking more senior programmers ;-)

---

Some examples of design methods to decide what the best possible options are:

• http://www.wikid.eu/index.php/Itemised_response
• http://www.wikid.eu/index.php/Weighted_objectives_method
• http://www.wikid.eu/index.php/Harris_profile
• http://www.mycoted.com/Brainwriting
• http://www.qicbok.com/tools/creativitytools_brainwriting635.cfm