Re: Help requested re Software Specifications
It's not a matter of determining the structure of the document
and writing it? I'll talk with the prospect tomorrow, but his
inquiry leads me to believe there are no people there now who
know about these types of documents.
If it's up to me to find a document structure or template, do you
have any specific suggestions?
Specific suggestion? Check the archives for references to IEEE and ACM, both of which have well established standards that a lot of organizations use. I don't think either offers their templates for free, but I could be wrong about that. In any case, the same archive check may turn up other possibilities.
That said, you have clearly understood the basic difference
between
functional and design specifications;
I'm not so sure that I do; there seems to be an awful lot of
overlap. And are "technical" and "design" specs the same?
You sounded clear in your understanding before. A functional spec is written, as you say, from the perspective of the user. Input --> Black Box --> Output. A design spec (sometimes separate from a technical spec, sometimes part of it) describes at a minimum what the user interface looks like; all the controls on all the screens or pages; all the language used for field labels, on-screen instructions, error messages; every possible consequence of every possible user action; all the calculations (the equations or algorithms to be used). The technical specification (if it is separate from the design specification) will include the database schema; the messaging protocols; a clear description of the architecture and the technologies involved; a breakdown of what goes where (what functions go in which layer, what goes into a .dll--or perhaps just into a header file or an include file--so it's available to all the modules); what coding conventions will be used (often specified in a separate document); what will be exposed in the API; maybe some other stuff I'm not thinking of.
I don't want to "struggle
through" them; I want to write them. If has existing documents,
so much the better, but as I said, my initial impression is that
there are no documents that I would be able to use as a guide.
But struggle you will, at least until you get the rhythm of the thing.
Writing a functional spec requires a deep understanding of the problem the software is going to solve and the environment in which the solution is going to be implemented. You have to be the customer, in other words, and think of every contingency, every usability issue, every interface to not only the human operator but also other systems, the office or factory environment, the Americans with Disabilities Act, the EU market regulations, ..., everything. How does the product _function_ in the world?
Once you understand the reality of the product's being in the world, the rest of the work consists of organizing the material sensibly (usually with deeply nested decimalized headings), breaking it down into teensy chunks (one requirement per heading, often a single sentence), and writing clearly and unambiguously (your major contribution when you're in a room full of engineers).
And the functional spec is the easy one ;-)
If the structure and design of every specification document is
different from company to company, then I have a great deal of
experience. But perhaps you are meaning something else. If so,
what do you mean?
I didn't mean it's all that different from company to company. I just meant it's very different from other types of writing you may have done and requires a somewhat different mindset. Content is king, and that's what you have to wrap your head around--the thing rather than the words used to describe the thing--in order to stand a chance of producing a usable spec.
Learning about the software is all that would be required to
write a specification, but again, I fear I may be
misunderstanding you.
Well, the specifications are supposed to exist before the software exists. The developers are supposed to find out about the software from you, not the other way around. The old joke goes, "It's a tight deadline, Marty. You go start writing code while I find out what the customer wants." It's a joke because a lot of specs get written after the fact, to satisfy a contract requirement. But that's not the way its s'pozed t' happen.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
SEE THE ALL NEW ROBOHELP X5 IN ACTION: RoboHelp X5 is a giant leap forward
in Help authoring technology, featuring Word 2003 support, Content Management, Multi-Author support, PDF and XML support and much more! http://www.macromedia.com/go/techwrldemo
From a single set of Word documents, create online Help and printeddocumentation with ComponentOne Doc-To-Help 7 Professional, a new yearly
subscription service offering free updates and upgrades, support, and more.
http://www.doctohelp.com
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.
References:
Help requested re Software Specifications: From: Bonnie Granat
Re: Help requested re Software Specifications: From: Dick Margulis
Re: Help requested re Software Specifications: From: Bonnie Granat
Previous by Author:
Re: Help requested re Software Specifications
Next by Author:
Re: Possible Memory Problem? Please help identify!
Previous by Thread:
Re: Help requested re Software Specifications
Next by Thread:
Help requested re software specifications?
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads