Re: README files: our job or their job?

["Nancy B. Delain" <nbdelain -at- ALBANY -dot- NET>]

It is hard to convince some people of the sensibility of having tech
writers do anything, isn't it? Certainly, a README file is indeed a classic
technical writer's task. It should be part of the documentation design of
any product, from the inception of the product (meaning predesign phase),
and should therefore fit into the overall scheme of the documentation. The
only person/group qualified to determine what fulfills this role is the
documentation person/group.

>>How does your company handle this?<<

I currently consult in a small startup (there are four employees; the
president/ technical guru, two marketers and a programmer). They view my
services as enough of an asset that they have kept me on after the
expiration of the first contract to continue to do documentation and
support for them. I guess I'm lucky; I get to set the standards (with input
from everyone else) of all documentation, paper, online, README. I may not
be much help to you here.

>>Do you have clearly defined responsibilities and procedures?<<

Yes. They're outlined above.

>>Do you have standards for README files?<<

We're still pretty new, so we're still developing our standards, so no, not
yet. However, they're on the list of stuff to work on in '97.

>From:
>Paul Baur (bap -at- software-ag -dot- de)
>Darmstadt, Germany

>There seems to be no concensus on (1) what goes into a readme file and (2)
>who is responsible for the coordination and creation of it. The only clear
>responsibility is that development delivers the input for it. After that,
>we seem to make things up as we go along.

>In some groups, the tech writer just proofreads the language; in other
>development groups, the documentor is expected to coordinate virtually
>every aspect of README "development", from organizing meetings to collect
>the information (some READMEs can be quite long), reviewing each entry,
>rewriting the information if necessary, ordering the information,
>formatting,  and ensuring that standards are kept to (assuming there are
>any).

>I view the README task as a "classical" tech writing task and I believe it
>belongs on the documentation plan (at the very end, of course). But I've
>met with some resistance here from tech writers who view the README as a
>development responsibility. How does your company handle this? Do you have
>clearly defined responsibilities and procedures? Do you have standards for
>README files? I am interested in developing such things for our company to
>mmake my job easier and our products better.


Nancy Baum Delain
Owner,
Delain Associates
Training * Technical Documentation