TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Your question reminds me that I never did send out a compilation of the
responses I received when I asked a similar question last week.
A "high-level spec" can be several things, but hopefully these links can
give you some ideas of what you and your company want to have in your
spec.
Thanks to everyone who responded to my earlier request.
Emily
=-=-=-=-=-=-=-=
I've had excellent results with a couple of client companies by using
Use Cases, which are then used to develop specifications. (You can
download my Use Case info PDF from my website at http://www.agnewcom.com/resources.html). Written use cases break the
product design down into tasks and features in a way that is user
focused and task oriented. The resulting specifications are then much
easier to write, and more complete. This approach also gets more people
involved at the design stage, so that there is a clearer collective
vision of what you're producing.
Many developers are familiar with the idea of use cases as they are part
of the UML methodology. Written use cases externalize that information
so that the product manager, techwriters, etc. can see what is going on.
This lightens the burden on the developers (who aren't always masters of
design) and shares the load among all the stakeholders. Typically, the
business analyst or systems analyst is the best person to write the use
cases, but they're not that difficult to create, so it could be any
member(s) of the team.
There's a bit of a learning curve for implementing written use cases
within a company, and they must have the will to do it right, but it can
>From the article intro:
"...This article will describe what an SRS is and why it's important,
discuss how and why technical writers should be involved with them,
and discuss the critical elements for writing an SRS. Although this
article does not attempt to address all aspects of developing SRSs,
it aims to help you determine the scope for such a project, to
provide some guidelines for writing SRSs, and to provide additional
resources."
Hope this helps!
Deborah
=-=-=-=-=-=-
(I can't find the original email from whoever sent me the "Joel on
Software" link. These articles on specs were not only witty but
useful....)
-----Original Message-----
From: Lisa Grijalva [mailto:lisag -at- airBB -dot- com]
Sent: Wednesday, February 19, 2003 12:04 PM
To: TECHWR-L
Subject: System Specs
I have been given the task of writing a high-level System Spec for our
small
company. This will be a new journey for me, as I've never written a spec
before, but I'm actually looking forward to the experience (sort of).
I have many questions, and would appreciate any help or suggestions.
What kind of information goes into a "high-level" spec?
Can anyone recommend a good template or resources on writing a system
spec?
Buy or upgrade to RoboHelp X3 today and receive the WebHelp
Merge Module for FREE ($299 value). RoboHelp X3's all-new
features include conditional text, completely re-engineered
printed documentation output, Context-sensitive Help Toolkit,
single-source layouts, and more!
Order online today at http://www.ehelp.com/techwr-l
---
You are currently subscribed to techwr-l as:
archive -at- raycomm -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.
