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.
long: Coincidence? I think not. Release Notes and READMEs
Subject:long: Coincidence? I think not. Release Notes and READMEs From:Alexia Prendergast <alexiap -at- SEAGATESOFTWARE -dot- COM> Date:Thu, 28 May 1998 17:54:09 -0400
Funny you should bring this up, John!
Over the past year our different sites have standardized on all the big
stuff (basic library structure, design, templates, architecture, tools,
etc.) However, we're having a friendly debate as we try to standardize
our release notes and READMEs.
We need to decide several things:
-Whether to have release notes, a README file, or both
-What exactly to include in the file(s)
(We've pretty much agreed already on format/media issues for the
different options.)
We do agree that:
-Users expect *something* (what they expect, we have different ideas on
-- some of which stem from the fact that we produce products for very
different user populations)
-We need to provide something that serves as the "it's too late for the
docs/help, but it's important enough that the user needs to know about
it" vehicle
So let me ask you this -- do you do release notes, READMEs, or both? If
you use both, do you just duplicate information or does each one have a
different purpose (which is what?)?
My instinct is to:
Include a single Release Notes file in hardcopy in the box and online on
the CD and from the web. The release notes include these topics (let's
ignore semantics such as bug fix vs. whatever-euphemism-you-use for
now):
* New features
* Upgrade/installation notes
* Bug fixes and enhancements
* Open bugs
* Documentation addenda
There are good reasons for handling this in any number of ways -- I'm
not looking for ammunition, but rather for your experiences and any
studies/articles to which you can point me.
Thanks!
A.
Alexia Prendergast
Tech Pubs Manager, Seagate Software
Durham NC USA mailto:alexiap -at- seagatesoftware -dot- com
> -----Original Message-----
> >I need to create a series of Release Notes for some software and I'm
> >interested in your opinion of what should (or should not) be
> included.
[Alexia Prendergast-->] ...
