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.
Re: Best places to put topics when they're needed twice
Subject:Re: Best places to put topics when they're needed twice From:"rebecca officer" <rebecca -dot- officer -at- alliedtelesis -dot- co -dot- nz> To:"Gene Kim-Eng" <techwr -at- genek -dot- com>, "Editor in Chief" <editorialstandards -at- gmail -dot- com> Date:Wed, 06 Nov 2013 14:06:49 +1300
Gene, I think you're majorly underestimating the complexity of some products.
We make computer networking hardware and the software that runs on it. Our most complex products have well over 100 major software features. Each major feature has between 1 and about 20 major options.
Some features and options are mutually exclusive, but most aren't. These are powerful flexible devices - there is no "typical" feature subset that most customers use.
Typical customers use somewhere between 1 and 10 of those 100 features. For each feature, they use between 0 and about 5 of the options.
Needless to say, we don't document comprehensive end-to-end configs for all valid set-ups!
Instead, we try to explain how each feature works, including all the options, and provide simple examples and config procedures for the most common uses of each feature. Customers have to glue the features together themselves. We have some end-to-end configs documented, but even those have to be heavily customised in practice.
Also needless to say, our document audience is trained network engineers, not the general public.
Cheers
Rebecca
>>> Gene Kim-Eng <techwr -at- genek -dot- com> 6/11/13 06:04 >>>
What you're describing is a product that needs a series of different
instructions customized to the each option so that users who are not
supposed to access certain features never see them, rather than one
single manual in which you describe them all and how to use them but
just tell the reader not to use them or that they're not allowed to use
them. These could be different PDFs, or OLH that is programmed to only
display the features enabled for specific configurations. Better still
would be embedded guides in the UI that walk the users through the
procedures appropriate for their configuration, but that decision is out
of the realm of documentation.
If you're writing for a regulated market, it's a mystery to me how
you're even being allowed to deliver manuals that provide users with
instructions for features they're not supposed to be using.
Gene Kim-Eng
On 11/5/2013 8:01 AM, Editor in Chief wrote:
> Say a product had ten major options that were best selected and configured
> during the unit setup, and those options affected performance, security,
> convenience, compatibility with widely-used third party products, etc.
>
> Say that some were mutually exclusive - simply wouldn't work with each
> other.
>
> Say that others can, and often do, work together, but don't need to, and
> occasionally shouldn't...
>
> Say that standards that a large chunk of customers must meet preclude those
> customers accessing certain of the major product features.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.
Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com
Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives
NOTICE: This message contains privileged and confidential
information intended only for the use of the addressee
named above. If you are not the intended recipient of
this message you are hereby notified that you must not
disseminate, copy or take any action in reliance on it.
If you have received this message in error please
notify Allied Telesis Labs Ltd immediately.
Any views expressed in this message are those of the
individual sender, except where the sender has the
authority to issue and specifically states them to
be the views of Allied Telesis Labs.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.
