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: [TechWhirl Forums] Authors who cannot write From:Lauren <lauren -at- writeco -dot- net> To:techwr-l -at- lists -dot- techwr-l -dot- com Date:Thu, 14 Nov 2013 08:13:46 -0800
I have dealt with this; this is how I got into technical writing 22
years ago. I agree with many of the suggestions posted here and there
are some that do not work.
What I have learned.
* Asking the people who want the document if they understand your
interpretation does not work because they hired you to make sense of
it and to tell them what it means.
* Asking the SME to make sense does not work because the SME thinks
the document already makes sense.
* Presenting the nonsense as it is does not work because when the
document fails, the technical writer gets blamed.
What you do is rewrite it to the best of your understanding and follow
Peter's suggestion of using short words. Use a strict active voice,
second person imperative to avoid getting trapped in the SME's vague
allusions to something that the SME assumes "everyone" knows. Write the
document with very short and very direct sentences in brief paragraphs.
If you are using Word (run it through Word, anyway) enable readability
statistics and run the grammar check. Keep the passive sentences low,
the reading ease high, and the grade level at 8 or below.
If the end result is that you have a document that tells someone to trip
a bomb with their left hand and then use their now blown off hand to
perform a task, then that is what the SME gave you. Give this document
back to the SME and tell the SME to assure you that the document is
correct and sign-off on it. Get that statement and "signature" in an
email that you keep with your records of the document. If the SME says
you got something wrong, then tell that SME what you provided is what
you were given. Learn to push back on the SME. It is not your job to be
a psychic and figure out what the SME is thinking.
The key here is to make sure that the SME has stated in writing that
what you prepared is what the SME said. You will be the last person to
touch the document and the first person blamed if something goes wrong
unless you have the SME's sign-off.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.
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
