RE: Writing functional specifications

Subject: RE: Writing functional specifications
From: Susan Harkus <Susan -dot- Harkus -at- xt3 -dot- com -dot- au>
To: "TECHWR-L (E-mail)" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 26 Sep 2000 09:15:52 +1100

Karen field wrote asking for "some resources for standards for writing/editing/formatting software functional specs?"

Different people have asked this question several times while I have been subscribing to the list. Last year, or early this year, when the topic came up, several people, including myself, supported the idea of approaching a functional specification as a document to be used by a number of different stakeholders and therefore with a structure and content that is determined by stakeholder needs.

(In fact, during the discussion I had some really valuable off-list discussions with a number of great people!)

I would strongly recommend, Karen, that you
1. Identify the people who will USE the functional specification. Test team? Developers? Documentation developers? Acceptance testers/users? others?
2. Find out what information they actually use in a functional spec. (= enables you to throw away traditional content that NO ONE reads or uses.)
3. Determine the content scope from your analysis. (= identify the target content that will answer stakeholder questions.)
4. Create a structure that enables people to read selectively and not have to go to various parts of the document to get their whole picture. Be particularly aware of how much people will be prepared to read!! Also, develop a structure that anticipates the maintenance cycle and tries to provide a productive maintenance platform.
5. Get agreement from all parties as to the authority of the functional spec for its content scope. (= is it the definitive specification for the full scope, or are other documents, such as data definitions, definitive in their target domain.)

I followed the above process a few months ago when developing a specification (template) for specifying web site page specs. The outcome was interesting because I hadn't realised the importance of step 5. In fact, I hadn't even thought there was a step 5.

Our web site development culture is to have the "creative" design of the site done by creatives, and the navigation model and page specifications done by the information architects. The creative designs are loosely based on the IA page specs but two separate information sources go to the page developers.

Which source of information do you think they use most readily? Correct, the creative designs with their colour and impact... so lots of nitty-gritty specifications fall through the cracks. Result? Iterative correction or just loss of good user experience.

A functional spec is a lot of work. It needs to be kept up-to-date otherwise it quickly becomes useless and document maintenance means more work. Given that so much effort is involved, it is worthwhile taking time to make the document useful for its stakeholders.

Susan Harkus
Sydney, OZ

Previous by Author: RE: Troubleshooting guide.
Next by Author: Mistranslations, idiom and humour
Previous by Thread: RE: Writing functional specifications
Next by Thread: Fiction and TW writers correction

What this post helpful? Share it with friends and colleagues:

Sponsored Ads

Sponsored Ads