Re: "How to Write a User Manual"

[John G <john -at- garisons -dot- com>]

Lynn said:
" there was no way I could plan out an entire document up front, without
knowing anything about the app I was going to write about. "  Waterfall
documentation!

I use a more flexible approach. I start with a Requirements Analysis:
Purpose, Audience, Topics Covered, Organization, Resources  ...  and use
them to organize my thoughts. I send it out for review wqhile I start
turning over rocks in search of information.

Then I do an outline - pretty much the same as you did in 8th grade to
chart the rise of western civilization - and incorporate the input I got on
the Req Analysis. Send that out.

Sample outline:

3. XMPL System Inputs
    3.1 Data Sources
    3.2 Data Receiver
    3.3 Data Checking

This gives you some idea of what Section 3 will contain.  However, you do
not have enough information to determine if a section written according to
this outline will tell you what you want it to, even if you have done a
good analysis of the problem.


Then I do the tricky it - an Annotated Outline. Basically it's an outline,
but with more data. All the previous steps have been as much to buy me time
for investigation as anything else.

An Annotated Outline that expands this example gives a better idea as to
whether the section of the draft will accomplish what you expect.
The Annotated Outline for the same Section 3 shown above might consist of
the following:

3. XMPL System Inputs
This section briefly (1 paragraph) lists and describes the types of inputs
XMPL handles, and introduces the contents of the remainder of the chapter.

3.1  Data Sources
This section (about 3 pages lists all the possible data sources
alphabetically.  For each data source, it describes where the data comes
from, what form it is originally in, and what you have to do before you can
load in into XMPL.

3.2 Data Receiver
This section (about 3 pages) describes:

   - What the receiver does, including searching for specified files,
   ensuring that files are complete, writing an output file, and deleting the
   input files once they are successfully processed.
   - How the receiver works including how it uses wildcards, performs
   specified volume/library, or total disk searches, how it uses transaction
   lookup file (TLF) functions, and explains session functions.
   - What the receiver requires, including the TLF and its  purpose and
   contents, the data input files and their requirements, and the control
   parameters.
   - How to tune the receiver to handle specific transaction types
   - How sessions are established and controlled, and how they are affected
   by the TLF and control parameters
   - Information about the session output file that is created


3.2  Data Sources
This section (about 2 pages) explains the data checking that XMPL performs
automatically, including listing error messages (alphabetically) and their
meanings;  explains the auxiliary checks that you can perform to obtain
more detailed information;  and explains the process you must follow with
error-free data.  There will be frequent references to Section 5: XMPL Data
Correction.

As you can tell, you get more usable information from the Annotated Outline
than from the outline.  You can evaluate the Annotated Outline to see if it
conveys the information you want in the way and in the order that you want
it, without having to create a draft of the section. Sending this out for
review gets you good input.

And again, you've bought yourself more time to learn that app. And to start
writing for real.

My 2Â

JG





On Tue, May 8, 2018 at 2:33 PM, Wright, Lynne <Lynne -dot- Wright -at- kronos -dot- com>
wrote:

> Its a basic overview, for people totally unfamiliar to tech writing, and
> is fine for what it is...
>
> Except this concept of a documentation plan is odd to me. When I started
> my first job as a tech writer, I was told to start with a documentation
> plan; but after a bit of head-scratching I abandoned it, because it was a
> chicken-an-egg situation: there was no way I could plan out an entire
> document up front, without knowing anything about the app I was going to
> write about.
>
> So in effect, my doc plan would have included the target audience, a scope
> of "describe every feature in the product", and a timeline of "have it done
> in time for the release of the software, which at this point, is only
> vaguely projected to be 'sometime in December/maybe january'". So... not
> useful in any way.
>
> The structure of the information was built/evolved as I worked through
> researching and documenting each feature. Developing a detailed "plan" to
> do that would have been a waste of time.
>
> -----Original Message-----
> From: techwr-l-bounces+lynne -dot- wright=kronos -dot- com -at- lists -dot- techwr-l -dot- com
> <techwr-l-bounces+lynne -dot- wright=kronos -dot- com -at- lists -dot- techwr-l -dot- com> On Behalf
> Of Cardimon, Craig
> Sent: Tuesday, May 8, 2018 9:17 AM
> To: 'TechWhirl (techwr-l -at- lists -dot- techwr-l -dot- com)' <techwr-l -at- lists -dot- techwr-l -dot- com
> >
> Subject: "How to Write a User Manual"
>
> Greetings,
>
> What are your thoughts on this article:
>
> https://clickhelp.co/clickhelp-technical-writing-blog/how-to-write-a-user-
> manual/
>
> Cordially,
> Craig Cardimon | Senior Technical Writer
>
>
>
>
> Information contained in this e-mail transmission is privileged and
> confidential. If you are not the intended recipient of this email, do not
> read, distribute or reproduce this transmission (including any
> attachments). If you have received this e-mail in error, please immediately
> notify the sender by telephone or email reply.
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Visit TechWhirl for the latest on content technology, content strategy and
> content development | http://techwhirl.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as Lynne -dot- Wright -at- kronos -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
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Visit TechWhirl for the latest on content technology, content strategy and
> content development | http://techwhirl.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as vwritert -at- gmail -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
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com

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

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