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.
Subject:RE: "How to Write a User Manual" From:"Wright, Lynne" <Lynne -dot- Wright -at- Kronos -dot- com> To:John G <john -at- garisons -dot- com> Date:Tue, 8 May 2018 19:34:09 +0000
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 -dot- 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"
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
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
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
