tech spec

[eanew]

can you throw your opinions on how to come up with  the good technical specification ? categorising the functional and non functional requirements ?

[Bruno.Cossi]

In my mind, the functional and non-functional requirements tell you what you need to build the technical specification for, they do not constitute the tech spec on their own. The finished model represents the tech spec.

What do you think?

Bruno

[sargasso]

The flow we use here, as we gradually move away from legacy methods is:

[1]Requirements Spec
[2] Analysis Spec
[3] Design Spec

Of these I guess our anaysis spec (actually called the Analysis Survey hint hint) is the closest to what you mean by the Tech spec.
It contains the conceptual or logical or "high" level interpretation of the requirements and can include:

• a Logical Behavior model, containing collaboration syle analyses for each use case implemented in the release
  
• an Analysis Class model, containing the "real world" level classes (i.e. before any patterns or other technical concepts are introduced) that arise from the behaviour model
  
• (optionally, if warranted by specific issues) state machine breakdowns for interesting classes and sequence diagrams for any interesting behaviour
  
• if warranted, a conceptual persistence model - preferably done in "crowsfeet" technique as the business people can understand the issues that are being discussed.
  
• optionally, if helpful, we include conceptual architectural models such as component and node diagrams to assist in the resolution of issues.
  

Now here's the rub... We do not insist that the analysis survey be a mandatory project deliverable.  If the nature of the system or system changes can be adequately resolved by moving directly from the requirements spec to the design spec, then we dont consider that the analysis survey adds any great value to the process.

It is used to assist in the development of the design.  That is, to explore technical options or issues at a conceptual - and often business - level.  

The design spec OTOH is fairly left up to the designers and developers.  The only mandatory item is the design class model, which we insist includes reasons why ccertain design decisions were made as these often are real at a particular time and fade later.

Bruce

[Rob_M]

I would suggest taking a look at the software requirements specification template suggested by Wiegers at:

http://www.processimpact.com/goodies.shtml

Tailor the outline to suit your needs, then model your packages in EA to mimic the tailored outline.

This worked quite well for us.

Rob_M

[fluxtah]

In the web world, some practicioners do have an artifact they call a 'Technical Specification'

In my mind this is not a 'technical' document from what I have seen. The ones we have at work, that some mad guy somewhere along the line decided to refer to it as technical is in fact a bunch of mock ups, which in the world of UML complement use case and UX modeling activities.

Now organising requirements into packages you need to know 'what' kind of requirements they are, are they functional, or non-functional?

some examples of functional:

The system should allow the Customer to order and buy widgets.
The system shall allow the Customer to track widget orders
The system shall allow the Customer to browse widgets.

etc...

Non-Functional:

The system should operate under sub-zero conditions.
The system should be available between 9-5
The system should have a consistent layout.


The way you group these into packages depend on the actual job, and once you start to gather many of these requirements package names should start to come naturally.

regards

Ian

[Stephen]

You may like to consider a couple of key heuristics as you build your technical specification,

whatever the final format you adopt.

Firstly, create a set of "highest" level requirements, written in a format and with language to suit

the Client. Present these as a set of "system goals" (or business goals). The idea is to create a

boundary for the system that will be "easy" for both parties to spot. It's worth including both

functional and non-functional aspects here - including some operating envelope parameters will give

you a set of sensible get-out's at the end of the project (Document the number of users or

transactions etc the system is designed to support - include some tooling to monitor this so you can

have a two pronged approach to performance issues). The driver here is to create a set of statements

about the system that are very unlikely to change during the lifetime of the project. This is not to

sya that this is just a business process analysis piece against your client, you just want something

that will help both of you identify when the Client askes for a change to far (...when you want to

ask for some extra money on a fixed price contract).

The other key element is to create a very clear bridge between these business goals for the system

and the artifacts you need to implement.

Flip into you analysis mode and create sets of use-cases, class diagrams and (say)

collaboration/communication/statechart models in parallel. Restrict your use-cases to the obvious

"what happens" stuff; put the "what does it" in the class model and the "in  what order" in the

communication diagram. Doing all three at once will help you cover all the bases and not get too

bogged down in the use-case (c4suc). The really anal modeller can rope the generation of sequence

diagrams in at this point also.... Doing the the models at the same time helps you make use of all

of the information captured on your CRC's while you can remember what you were thinking.

To form the links between the business and the technical worlds map the use-cases onto the "goals".

For clients with a little bit of an engineering background create something like a work breakdown

structure under your goals to clearly key some deliverables (use-cases) to some particular element

(functionality) of the system. Only put prices on these links (stops you charging for something the

Client can't validate).

Don't try to do all this for the User interface esp. on a browser delivered system. Try to keep all

UI discussions in a separate stream (can still document client-side functionality in same way, just

don't get into detailing screen layout). The XP practitioners don't want to deal with this yet, the

waterfallers only need a storyboard anyway(!)
Similarly for data issues - system meta-data manangement, data migration etc.
I also hive off reporting issues because I mainly service clients within the same group of companies

or external organisations with their own I.S. dept.

As I try to live with my organisations processes I phase my projects as small as I can get away

with, do a couple of iterations of the above at the highest level I can manage without getting

vertigo. Then use what I've learnt to take a stab at a price. As long as the "goals"are solid I can

generally price safely, then flesh out the technical side for each phase (release!) as I get to it.

Just got to get a bit more flexibility into the off-shore dev. team now......

Hope a bit of the above fires some useful ideas

Stephen