Re: Other kinds of technical writing

[Barbara Karst-Sabin <barbara -at- QUOTE -dot- COM>]

So much depends on the individual.  Many engineers write beautiful
documentation without prodding, just as a matter of course.  Others
would need a gun to their heads and then would turn out drek.

Even if the engineers write internal documentation, they really need
someone (like a tech writer) doing documentation management.  Trying to
corral a lot of miscellaneous docs, avoid duplication of effort,
establish some kind of consistency, maintain version control -- all
those kinds of things almost always go by the wayside when you don't
have a documentation professional somewhere in the loop.

So it's not a matter of should you expect them to, but can the engineers
at your company do it?  And who's going to manage the docs once they are
written?

BJ

> Ben Kovitz wrote:
> >
> >Well, let me rephrase the question, then.  Should system analysts,
> >programmers, engineers, etc. be expected to write internal technical
> >documents of reasonable quality, or is this kind of writing best treated as
> >a specialized skill, requiring specialized training or talent that you
> >shouldn't expect of a programmer?  Should you hire a separate person to do
> >this job for the engineers, treating the engineers as SMEs, or should the
> >engineers normally do it themselves?  What's the best division of labor?
> >
> >Or in other words, is expecting programmers to write good technical
> >documentation the same fallacy as expecting programmers to design good user
> >interfaces?
>
> In our company, for each external project we must produce the usual suite of
> IEEE conforming documents: requirements specifications, design descriptions,
> plans of all shape and form, and of course, system functional descriptions.
>
> I have tried to ease the process by creating extremely detailed templates to
> guide the engineers. (In my experience, engineers write everything they know
> about a product/box/software item in one location, then hand it back to
> me...but they're getting better.) In my role as editor/writer, I tend to
> move things around a lot. For example, in our current project I got good
> info on error messages and memory usage....in the requirements
> specification. I know enough to move it along to the design document, clean
> it up, check it for consistency, and then 'pretty it up'.
>
> Programmers, engineers and analysts should know enough to make a significant
> 'first pass' at such documents, but there should also be a separate person
> guiding the whole process. (I also manage to catch technical errors - "Joe,
> in your software document you say the system produces output X. But Jane's
> hardware document says that she gets output Y from you. Which is correct?")
>
> I know for a fact that I'm the only person in our organization who has ever
> read any of the IEEE document specs, and everybody here likes it that way.
>
> Ginna Watts, Technical Writer
> Quester Tangent Corporation
> Sidney, BC
> gwatts -at- questercorp -dot- com
>
> From ??? -at- ??? Sun Jan 00 00:00:00 0000==


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=