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: Quality of source material from Development From:"Jane Carnall" <jane -dot- carnall -at- digitalbridges -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Tue, 11 Dec 2001 16:44:54 -0000
Salan Sinclair asks:
-----Original Message-----
How much written information should software development department provide
for a technical writing department?
Option 1. Enough for tech writers to write the documentation, with few
questions.
Option 2. Enough for tech writers to get a complete scope but not the
details.
Option 3. Enough for tech writers to get started, or whatever information
developers can provide in the time allowed.
--------
IME, the Dev Manager will always expect Option 1 (We gave you the spec and
the code! What do you mean, you want to bother us with questions???) whereas
Option 2 is (IMO) preferable. (Option 3 is rather fuzzy-edged.)
Unless you are a programmer who can write (rather than a technical writer
who can read a bit of code) the information is always going to have to be
dug out of the SME brains by whatever means are most convenient to all
concerned.
The most compact way of getting the information the technical writer
requires may be for the developer to write it down - "Re. your e-mail on how
to flubdub the essgee, look at the code in section 3.7 and here's links to
some helpful material we read when we were developing that section.
Flubdubbing is complex and takes the following priorities - we've set up
Essential, Humungous, and Rare, they can add others if they like but they
need to be careful they don't overgoggle the wifwaf or they won't be able to
essgee at all. Plus this impacts on zetaing the jibjab, you might want to
refer to that."
The way I find is easiest all round is to look at what source material there
is, ask for helpful pointers to background information (and do a lot of
background reading, obviously, as one link follows to another), create an
alpha draft document and go back with more questions. The developers *have*
the information: but it's the technical writer's job to get it all together
and figure out how to structure it and make it consistent and useful and
helpful. If the code is well-commented* and the spec is accurate**, the spec
and the code (and pointers to background material) are an excellent starting
point. But further questions will *always* be needed, and the SMEs should
*always* be persuaded - by whatever means necessary - to provide a technical
review.
Jane Carnall
Apologies for the long additional sig: it is added automatically and outwith
my control.
E-mail is an informal method of communication and may be subject to data corruption, interception and unauthorised amendment for which Digital Bridges Ltd will accept no liability. Therefore, it will normally be inappropriate to rely on information contained on e-mail without obtaining written confirmation.
This e-mail may contain confidential and/or privileged information. If you are not the intended recipient (or have received this e-mail in error) please notify the sender immediately and destroy this e-mail. Any unauthorized copying, disclosure or distribution of the material in this e-mail is strictly forbidden.
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of
your book. What are you waiting for? http://www.iuniverse.com/media/techwr
Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
