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.
I like Geoff Hart's suggestion of setting up a regular lunch seminar to
focus on one aspect of writing. Since you already have a friendly
relationship with the developers this might be very well received. Two
other things that were helpful for me in a similar situation: A cheat
sheet and a template.
The cheat sheet is simple: a list of common problems, such as its/it's,
their/they're - customize it to the things you are seeing the most. The
cheat sheet should be one page at most. Send it via e-mail, but also
print it and hand it around so people have it "right there" when they
need it For example,
it's - Short for "it is"
its - Belonging to it (possessive)
If they don't already have a template for their work products, you can
put one together that has the items that are commonly included. You can
also give hints in the template to remind them how to used it. For
example, if it were an API description, you might have something like
this, where the notes in braces will be replaced by the writer
API Overview
[Two or three sentences about what this API accomplishes, and what
important things the user needs to know.
Start with a verb, like Creates, Updates, Deletes, Searches.
For example "Creates a new employee entry, and generates an employee id.
The employee entry has only the employee name and ID. Use UpdateEmployee
to add the rest of the employee data"]
Restrictions
[List any important constraints. Try to state the constraint positively.
For example
"Use only if the connection has already been created."
not
"Don't use if the connection has not yet been created."]
Detailed description
[Describe any relationships between the parameters in the API. Describe
likely uses. You do not need to describe internal system workings, such
as how the database will be updated. Any possible exceptions should be
described in the exception section below. Keep it in the present tense.
For example:
"CreateEmployee takes two required strings, employee first_name and
last_name, and creates an entry in the Employee database. The return
value is a string that is a unique id generated by the system, which is
used to identify the employee."]
....etc.
I found that while people still struggled, using a template helped a
lot, because it reminded them what they were supposed to say, and how
they were supposed to say it. I got a lot of "parroting" of the
examples, but at least things were more consistent, if occasionally a
bit more stilted.
WEBWORKS FINALDRAFT - EDIT AND REVIEW, REDEFINED
Accelerate the document lifecycle with full online discussions and unique feedback-management capabilities. Unlimited, efficient reviews for Word
and FrameMaker authors. Live, online demo: http://www.webworks.com/techwr-l
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit http://www.techwr-l.com/techwhirl/ for more resources and info.
