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.
A couple weeks ago I posted a query about types of docs needed for
documenting hardware and whether they needed to be MIL spec. I also promised
to summarize the responses for the list, so here goes. I've grouped the
comments by Types of Docs, Testing and Standards, Milspec (and Other Specs),
and Recommended Websites. A big thank you to Rick Lippincott, Martin Polley,
Jennifer Pinkley, Lisa Wright, Matt, Carly Martin, Michael Shea, and Mike
Bradley for their advice and suggestions!
TYPES OF DOCS
* Preliminary Instructions. Your users have just pulled the item out of the
box. What do they have to do to make it operational? If it's a component
that goes into a system at a telecom center (like a switch), then you'll
need installation instructions. Does it require that the users install
software? If so, you'll need the software installation instructions as well.
Do they have to configure any settings? If so, you'll need configuration
instructions.
* Operation Instructions. How do the users turn it on? And once it's on,
what are the steps they have to go to use it. Included in this: what are all
the features that area available to the user? What do all the buttons do?
Are there menu screens? If so, you'll need to show them all, and explain
what the meaning of each selection on the screen is, and what the user can
input in response to these selections.
* Maintenance Instructions. Are there periodic inspections and/or cleanings
the user must do? Also include troubleshooting: what symptoms of
malfunctions should the users look for, and what do they do in response. Are
there batteries that need to be changed? If the device can be opened up for
maintenance (like a PC, for example), you'll need to include all the steps
to do this. If the users can replace certain parts, you'll need to include
steps for the removal and reinstallation of those parts. (You'll have to
check with your managers and the design team to find out which parts are
authorized for user replacement.)
* Spare parts ordering instructions. Include a list of all the parts that
the customer can order.
*For each hardware device provide a user manual starting with FCC
rules/regulations about the device at the beginning of the manual. This is
very important to include if applicable. We had a general page of FCC info,
then a page about radio frequency interference. If the product will be sold
in numerous countries, you will need to find out what information each
country requires. We had a packing list that outlined every piece of
equipment the user should have received (that was really in the first
chapter after the product introduction). We also had technical drawings of
the device and callouts to describe everything on the device (even things
that I wouldn't have thought to label).
*There isn't a whole lot of information that's very different from software.
Just explain how to install the hardware, how to configure it, how to
troubleshoot it, and include technical support contact info.
*If there are different kinds of connectors/cards/accessories/additional
devices that go with this device, and if the user has to choose between
those different connectors etc., it would be helpful to provide
illustrations of each, including proportions / dimensions if necessary.
*Marketing Requirements Document (MRD): what the customer needs Product
Requirements Document (PRD): more technical description of requirements
Functional Specifications, Design Specifications Test Plan, Test Cases, Test
Results (these should directly support the requirements)
*The kind of documents you need are dependent on the needs of your customer.
I am currently documenting telecommunication equipment. The kinds of things
that need to be described are as follows: How do I physically install it.
How do I get it running. How do I install and operate the management
software. How do I maintain the equipment and troubleshoot problems. What
are the features of the system and what do they mean or how does it fit in
the big picture.
*Since the audience will be techies, I would follow a top-down outline in
each chapter. It's the techie way, that is, it's how engineers are educated.
Start with a very high-level description, just a paragraph or two crammed
with keywords. Follow that with a section elaborating on the keywords.
Follow that with the detailed sections of the chapter.
TESTING AND STANDARDS:
* A test plan, which describes the tests that will be carried out, and the
expected results of the tests. It also includes references to any relevant
specification or design documents (which specify what the system should do)
or standards (see below). Our test department uses this document when
performing the actual tests. (Bear in mind also that in some cases, certain
tests must be performed BEFORE other tests. The document may also spell out
when to quit testing and go back and fix problems, before starting over with
the tests.)
* A test results document, which gives the results of each test described in
the plan, with an indication of whether the system passed or failed each
test. It also includes a list of bugs that were discovered during testing
(and that were not solved before the release). (Our products are a
combination of hardware and software, so this part may be less relevant for
you.)
*The people who designed the product (whatever it is) should have a pretty
good idea of what it is meant to do, and which standards it should meet (for
telecom stuff these will often be ITU (www.itu.int) or TIA
(www.tiaonline.org) recommendations (or 3GPP for cellular -- www.3gpp.org)).
*In our case, we work very closely with the testing department on these
documents. We (the technical writers) do not decide what tests are carried
out, or what the results should be. Our role is to give structure, logic and
format to the material that they provide us.
MILSPEC (AND OTHER SPECS):
*MILspec is only necessary for the military or if that is what your customer
prefers. It isn't required by the telecom business, nor the semiconductor
business; the other hardware writing that I have done.
*The docs only need be written to MIL specs if you're selling them to the
U.S. Department of Defense AND the contract requires it. If this is the
case, the contract likely specifies which MIL spec applies.
*Because it is a telecom product (and I'm going to assume it is -not- going
to the U.S. DoD), you -may- wish to follow Bellcore specs. This isn't a
requirement, but it's not a bad idea. You can start with Supplier
Documentation for Network Elements (TR-TSY-000454) and Guidelines for
Product Change Notices (TR-TAP-000209).
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check out SnagIt - The Screen Capture Standard!
Download a free 30-day trial from http://www.techsmith.com/rdr/txt/twr
Find out what all the other tech writers, including Dan, already know!
All-new RoboHelp X3 is now shipping! Get single sourcing, print-quality
documentation, conditional text and much more, in the most monumental
release ever. Save $100! Order online 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.
