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: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)
Note: This is my opinion. My employer usually has a different one.