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.
With any luck you've already solved this, but hey, it's Friday afternoon. :-)
Not surprisingly I can't quite tell what it is that you're trying to explain. As a writer of software documentation, I've had many problems of this sort myself; I usually start by giving myself permission to be as verbose, colloquial, and specific as seems to be necessary to get an accurate, comprehensible explanation down on paper. Then I try to tighten it up.
So in this case, you might start with an annoyingly long paragraph (or maybe a bullet list) of this nature:
You can now add a bill code, or recurring billing amount, to customer accounts. You can do this only for customers who have xyzzy bill code already on their account. You can also obviously remove the bill code, but only once it's been added, and only for customers who.....
(Just by doing this exercise, I've noticed that you may not want to lump "add or remove" together the way you've done it. I have a suspicion that's messing with your logic.)
Hope it helps,
From: Joe Weinmunson [mailto:litlfrog -at- gmail -dot- com]
Sent: Tuesday, April 19, 2011 7:34 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Phrasing question for software documentation
I'm trying to document a new global change that our billing software
can make. Our userbase is generally not very tech-savvy. The change
adds or removes a "bill code" (that is, a recurring billing amount)
for a large number of customers at once. The option I'm stuck on is
explaining a conditional setting. The user can choose to add or remove
the bill code ONLY from customers who already have a certain bill code
on their account. Every time I try to write something that makes
sense, MY eyes glaze over. Anyone have advice on this? Thanks.
Have nothing in your house that you do not know to be useful, or
believe to be beautiful.
Create and publish documentation through multiple channels with Doc-To-Help.
Choose your authoring formats and get any output you may need. Try
Doc-To-Help, now with MS SharePoint integration, free for 30-days. http://www.doctohelp.com
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-