RE: Question about parallelism in lists

["Leonard C. Porrello" <Leonard -dot- Porrello -at- SoleraTec -dot- com>]

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


-----Original Message-----
From: techwr-l-bounces+leonard -dot- porrello=soleratec -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+leonard -dot- porrello=soleratec -dot- com -at- lists -dot- techwr-l -dot- c
om] On Behalf Of Joe Weinmunson
Sent: Tuesday, May 04, 2010 7:18 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Question about parallelism in lists

This is a question about writing standards and readability, not any
technical issue. I'm documenting some software screens. Here's a copy
of the current file:
http://roleplayhistory.com/trashflow/Rates.html

I'm using an unnumbered list to explain the fields on this tab. This
screen is more important than most in the program, so I'm going into
detail about what they do. I know that when explaining fields like
this it's normal to use parallel construction in the explanation:
"This field does X", "This field does Y", etc. Trying to use those
conventions to explain the functions on this screen just seemed
forced, though. Does anyone care to offer an opinion as to whether
it's worthwhile to try and find a way to explain these fields in a
more standardized way, especially if the way it's currently written is
confusing? Thanks.

-- 
Joe Weinmunson

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/ for more resources and info. 

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat