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: Question about parallelism in lists From:Joe Weinmunson <litlfrog -at- gmail -dot- com> To:techwr-l -at- lists -dot- techwr-l -dot- com Date:Tue, 4 May 2010 14:29:29 -0400
First off, many thanks to everyone who replied. I appreciate your
taking the time to help me. At a minimum I'll rewrite the entries for
consistency and begin each item with a task-based instruction. I may
switch to tabular format and I'll certainly move the screenshot; it
was only in the middle because I wanted to break up the "block of
text" effect in the middle of the page. I'm actually new to technical
writing as a profession--I've been at this job less than a month. I
have experience in academic writing, tech support, and internal
documentation, but this is a much bigger project than anything I've
worked on before. It is indeed fun, though so far I'm alternately
writing in bursts of activity and flailing in indecision. The page I
posted was inherited from a 15-year-old manual, but I had already
rewritten parts of it. From the sound of things, I still have a lot of
work to do. :)
On Tue, May 4, 2010 at 11:56 AM, Leonard C. Porrello
<Leonard -dot- Porrello -at- soleratec -dot- com> wrote:
> First, please accept my condolences and congratulations. Condolences for
> having inherited such a poorly written and inferior document.
> Congratulations on the opportunity to demonstrate that a professional
> technical writer is worth his or her wages.
>
> Several thoughts and observations:
>
> It's best to avoid violence in technical writing. For example, we don't
> "hit" keys; we "press" them.
>
> I am pretty sure that "screen" is worst name you can use for a dialog or
> window.
>
> I couldn't find a "Bill Codes" field. I had to deduce that "Bill codes"
> refers to "Code." Seems like an inauspicious way to start.
>
> I can't easily tell which fields are populated by the program and in
> which I have to enter data.
>
> The bullet points above the screen shot are descriptive. Several below
> the screenshot are prescriptive. I wonder why. Also, the first five tell
> me what type of control I am dealing with. Not so with the rest.
>
> I don't understand why the screen shot is in the middle of the page.
>
> In general, I find the layout unattractive and difficult to read. I
> would seriously consider information mapping the whole thing. If that is
> beyond your scope, the page still needs extensive rewriting, and I would
> suggest that you add some space between bulleted items.
>
> And finally, in response to your question, yes, parallelism is
> essential. Parallelism makes it easier for readers to find exactly the
> info they need. If it seems forced, you need to rethink your paragraph
> and sentence structure. Again, I would use an approach informed by info
> mapping even if I couldn't info map the page.
>
> Leonard
>
>
--
Joe Weinmunson
Have nothing in your house that you do not know to be useful, or
believe to be beautiful.
--William Morris
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Use Doc-To-Help's XML-based editor, Microsoft Word, or HTML and
produce desktop, Web, or print deliverables. Just write (or import)
and Doc-To-Help does the rest. Free trial: http://www.doctohelp.com
- Use this space to communicate with TECHWR-L readers -
- Contact admin -at- techwr-l -dot- com for more information -
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
