Re: "How to Write a User Manual"

[Chris Morton <salt -dot- morton -at- gmail -dot- com>]

I'm in Lynne's camp.

The post was clickbait for Clickhelp. Its content manager had a piece
scheduled from that "author."

Said "author" whipped something up that looked OK to the content manager,
who has never written a user guide. And so the cycle continues.

I'm handling a lot of this stuff today for several clients who are smart
enough to understand that the "authors'" submissions need to be copyedited
by a pro. That be me.

Meanwhile the "authors continue to turn in first draft drivel, complete
with gems like this:

The log query *too* 4 hours.  I didnât get to *best* last night until 3 am.


Last week another "author" sought to *alley* readers' fears.

But hey, at least these people ran spell check, right?   ð

There's a terrific passage in Stephen King's *11/22/63* where the
protagonist teaches GED English during evenings... something about tons of
red ink and being driven stark-raving mad, mad, mad....*MAD!   ð*

All this to say I'm so glad I'm not an English teacher who has to grade
essays, term papers, and such. There would be much carnage. Bodies
everywhere. "Want red ink? Why, I'll SHOW you red ink!!!!"

Chris Morton
(click logo â for details)

<https://www.the-efa.org/memberinfo/chris-morton-10670/>
      â Substantive Editing â Technical Writing â Proofreading
                   â B2B/B2C â Marketing Expertise â Mentoring



On Tue, May 8, 2018 at 4:28 PM, John G <john -at- garisons -dot- com> wrote:

> That's not how I do it ... that's how I taught my students to do it. I take
> Red Barber's approach - just sit down at the keyboard and open upstairs a
> vein.
>
> JG
>
> On Tue, May 8, 2018, 3:34 PM Wright, Lynne <Lynne -dot- Wright -at- kronos -dot- com>
> wrote:
>
> > If all that planning helps you, then great. But based on my experience,
> > that seems like a lot of unnecessary work to just describe what I intend
> to
> > do, providing that things go the way Iâm guessing that they will, that
> > there will be no surprises or things I hadnât known about when I
> developed
> > my outline, and that nothing will change throughout the months during
> which
> > the software is being developed and evolving. And things ALWAYS change,
> > whether its things being taken in or out, or the delivery date being
> pushed
> > back, or whatever.
> >
> > But its not like I just jump in anywhere and totally wing it; there is
> > always an implicit plan or outline, ie: 1) Basic intro/overview of what
> the
> > product is/does 2) System Setup, including basic configurations 3)
> Overview
> > of user interface 4) Describe features in the UI in a logical order that
> > follows how features would be applied in real life (ie if you canât use
> > feature B without understanding feature A, explain feature A first), 5)
> > Customization/defining user preferences.
> >
> > However, I donât necessarily do my research/writing in that order.
> > Typically Iâll start by documenting the UI and the user-facing features
> > because they tend to be easier to figure out and explain, and because
> then
> > I can pass that content on to Training so they can build course materials
> > from it prior to the go-live; and so I can create a help system to
> > integrate into the software. Since our products are generally delivered
> > pre-configured for the customer, the setup and config info, which tends
> to
> > take a lot more research to learn and understand, can be done later.
> >
> > And then once the baseline documentation is done, if features are added
> or
> > modified, its pretty easy to figure out where to stick them into the
> > existing material without making a plan.
> >
> > From: vwritert -at- gmail -dot- com <vwritert -at- gmail -dot- com> On Behalf Of John G
> > Sent: Tuesday, May 8, 2018 2:57 PM
> > To: Wright, Lynne <Lynne -dot- Wright -at- Kronos -dot- com>
> > Cc: Cardimon, Craig <ccardimon -at- m-s-g -dot- com>; TechWhirl (
> > techwr-l -at- lists -dot- techwr-l -dot- com) <techwr-l -at- lists -dot- techwr-l -dot- com>
> > Subject: Re: "How to Write a User Manual"
> >
> > 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
> > <mailto: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<
> mailto:
> > kronos -dot- com -at- lists -dot- techwr-l -dot- com> <techwr-l-bounces+lynne.wright=
> > kronos -dot- com -at- lists -dot- techwr-l -dot- com<mailto: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<mailto:
> > techwr-l -at- lists -dot- techwr-l -dot- com>)' <techwr-l -at- lists -dot- techwr-l -dot- com<mailto:
> > 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
> > <mailto:Lynne -dot- Wright -at- kronos -dot- com>.
> >
> > To unsubscribe send a blank email to
> > techwr-l-leave -at- lists -dot- techwr-l -dot- com<mailto:techwr-l-leave -at- list
> s.techwr-l.com
> > >
> >
> >
> > Send administrative questions to admin -at- techwr-l -dot- com<mailto:
> > admin -at- techwr-l -dot- com>. 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<mailto:
> > vwritert -at- gmail -dot- com>.
> >
> > To unsubscribe send a blank email to
> > techwr-l-leave -at- lists -dot- techwr-l -dot- com<mailto:techwr-l-leave -at- list
> s.techwr-l.com
> > >
> >
> >
> > Send administrative questions to admin -at- techwr-l -dot- com<mailto:
> > admin -at- techwr-l -dot- com>. 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 salt -dot- morton -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