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.
In my experience, whenever a developer comes to you and says
"We really need some bonafide writing talent to make or
process better... What we need is a 'scribe' for the
development department," you should run. Run, and don't
look back. Run as though your life depends on it.
Ultimately, when lean times come, that position will be the
first to go, and the person who championed it will have
moved on to another company. I fell for this line twice in
two different companies, and I wound up scrambling to find a
valuable contribution to make.
In a more general and perhaps (you might think so, anyway)
more serious vein, I strongly advocate the engineers writing
their own docs. If you need to use them, and you should,
*there* is your chance to establish that they say exactly
what the developer wants them to say. You do that by
understanding the issues sufficiently to know when you don't
understand; this is not as easy as it might appear. Then
you go to the developer and ask questions. At that time, if
the developer wants you to incorporate changes, I suppose
you can offer. But it would be a better world if the
developer owned the document entirely and made his own
changes.
There is literature out there to show that time spent
specifying a project is easily saved when it's time to code
it. Presumably, your company is already aware of that
concept, or you wouldn't be worried about this. One part of
the specification process should be review. That is the
best place for you to be included in thedevelopment process,
IMHO. You can serve as a user advocate, and you can also
indicate areas that will be impossible to document,
localize, etc. You can also suggest useful additions to a
functional area. And I have found, in reviewing specs, if
the function seems very difficult to document, it probably
needs further design. Not only will it be hard to use, but
the underlying archetecture is probably suspect as well.
But once a developer has been convinced that he must create
the spec, I have yet to find one who wants me to actually
touch the content. He wants me to suggest changes. And I
will also point out that you should not waste your time on
grammar or spelling, except for terms that appear in the
User Interface. Organization, comprehensive coverage, and
clarity of concepts are all that matter. Anything else is
fluff, re internal docs.
As for formatting, it should strictly and rigorously serve
organization. In fact, it is a very good idea to have
templates that include sections for every category that
needs coverage. And those sections should be in place, with
titles for each category, and the body of each section
should define the category. Then a developer merely needs
to go through the template and replace the existing text
with his own meaningful prose. Needless to say, the specs
must be designed by committee... Q/A might want a specific
section in each spec, as might Documentation. For example,
we needed each spec to provide very specific information
linking a function to context sensitive help. Q/A needed a
section describing the upper and lower limits of various
data. But this comittee should focus on categories, not
format. Maybe you can volunteer to translate the structure
into a useful graphic design. Let me stress "useful" here.
In my experience I have only once proved useful in editing
and manipulating an engineer's documents. That was for a
Japanese engineer who's english was absolutely unreadable.
My job was to convert his documents into something the other
developers could use, all the while ensuring I said what he
meant. But that was a very special case.
Finally, I forget who it was, but it might have been
Aristotle who said something like, "I have never really
thought about a subject until I have written about it." I
submit that as my final argument as to why the developers
should have total ownership of their specs and design docs.
Let them experience the full rigor of making a comprehensive
and understandable artifact in a natural language.
Sorry this turned into a rant. This is just my own opinion.
