README files: our job or their job?

Subject: README files: our job or their job?
From: Paul Baur <bap -at- SOFTWARE-AG -dot- DE>
Date: Fri, 6 Dec 1996 10:47:35 +0100

I'm a technical writer in a system software company. Being a mature company, our documentation procedures and responsibilities are fairly well defined and documented. One weak spot I recently discovered was the README file.

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 README 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.

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

Note: This is my opinion. My employer usually has a different one.


Previous by Author: Re: Sense of Humor Testing
Next by Author: Network management - eng-swe
Previous by Thread: Re: Publishing Tool Djihad
Next by Thread: Re: README files: our job or their job?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads