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.

Learn more: http://bit.ly/ZeOZeQ

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as rebecca -dot- officer -at- alliedtelesis -dot- co -dot- nz -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

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.

Learn more: http://bit.ly/ZeOZeQ

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

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


Follow-Ups:

References:
Best places to put topics when they're needed twice: From: Editor in Chief
Re: Best places to put topics when they're needed twice: From: Gene Kim-Eng
Re: Best places to put topics when they're needed twice: From: Editor in Chief
Re: Best places to put topics when they're needed twice: From: Gene Kim-Eng
Re: Best places to put topics when they're needed twice: From: Editor in Chief
Re: Best places to put topics when they're needed twice: From: Gene Kim-Eng

Previous by Author: Re: "A few things tech writers frequently say"
Next by Author: Re: Standards for command-line documentation + dumb Acrobat X user question
Previous by Thread: Re: Best places to put topics when they're needed twice
Next by Thread: Re: Best places to put topics when they're needed twice


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads