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.
Requirements Specifications are often not a single document, but usually a
set of documents. Three important ones are:
Business Requirements
Technical Requirements
Use Cases
If you haven't been involved in Requirements gathering, I would direct you
to attempt to determine, collect, etc. the Business Requirements first.
These requirements may seem trivial at first, but they end up driving key
aspects of all other requirements. Examples of bus requirements may be
straightforward: the software product must be sold for under $50. But is
may look like a technical requirement: The software product must support 3rd
party plug-ins. There may not be a host of Business Requirements, but they
are all very important. These are usually the hardest requirements to get
unless you have very good Product Managers and Business Strategists.
Secondly, All requirements are hierarchical in nature. That is, top-level
requirements drive lower level requirements. If you are collecting
requirements and have collected a bunch of technical requirements that do
not seem to connect to any upper level requirements, then you must go back
to the top and see what you have left out. Sometimes this means writing
down things that are so basic that it seems trivial (e.g., this product must
have a GUI). It is not. If the basic assumptions change, then all lower
level requirements driven from those assumptions change.
Third, do not give up.
Fourth, contrary to other advise given on the list, I think you should write
as furiously as possible and create hierarchy trees so that as you are
collecting things you are creating order at the same time.
Fifth, You may not get people to review your work, but depending on the
software/hardware culture, the architecture and design will be driven
directly from the requirements. Often the architecture and design specs
must reference the tech and bus requirements. This brings me to use
cases...
Sixth, Use cases can help in the determination of low level technical
requirements. They are less useful for top level requirements as they are
based on assumptions of given interactions (which are driven from top level
requirements).
Analysis of Use Cases will often shed light on the missing top level
requirements as well as provide multiple levels of technical requirements.
Some engineers do not write requirements well, but can create many very
in-depth and insightful use cases. Work within your culture, but funnel
things back into the requirements docs.
Seventh, do not give up. Unless you are working for a DOD company, the reqs
may never be completed. That's OK. In many companies, the process is as
important as the final document. It gets people thinking about business
models and technical responses to them. Somewhere in the mix, software is
designed and deployed.
Finally, Number all your requirements. BUT don't renumber as you go. Just
retire the numbers. Consequently, you may not want to assign numbers to
requirements until you are somewhat satisfied you have most of the major
categories for the architecture/design/business model defined. Then, don't
number consecutively, start with numbering by 5's or 10's. This allows you
to fill in related requirements, etc. Use some scheme like <category
number/acronym>.<subcategory number>.<req number>, for example, BR10.2,
GUI4.5, etc.
Someone may want to trace your requirements up and down. So as you are
writing the specs, think about how you will handle traceability.
Hyperlinks, tables, etc. You don't have to start with the right format, but
at some point, you should begin to organize the documents for traceability.
If the requirements are complex enough, you may want to include a map of the
major sections.
Huge disclaimer here: Of course, if you are under someone's thumb that has
different ideas, different timelines, different models :), go with those.
New from Quadralay Corporation: WebWorks ePublisher Pro!
Completely XML-based online publishing. Easily create 14 online formats, including 6 Help systems, in a streamlined project-based workflow. Word version ships in June, FrameMaker version ships in July. Sign up for a live, online demo! http://www.webworks.com/techwr-l
---
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- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit http://www.techwr-l.com/techwhirl/ for more resources and info.
