Re: "How to Write a User Manual"

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

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- lists -dot- techwr-l -dot- 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- lists -dot- techwr-l -dot- 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 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