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:Re: Revision History in Readme? From:Sandy Harris <sandy -at- storm -dot- ca> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Fri, 29 Dec 2000 12:18:53 -0500
Melanie Shook wrote:
>
> Historically at my company, the readme has included a revision history,
> which lists all of the bug fixes and feature additions ever made. Now that
> the product is becoming more mature, this list is getting extensive.
>
> Is this typically done? This is a consumer product. Is there some value to
> including a revision history that I don't get? (Last time I mentioned
> getting rid of it, the lead developer wanted to keep it, and being new at
> the time, I deferred to his judgment.)
I'd say keep it (make developer happy), but in a separate file (don't clutter
the Readme).
> The readme has features and enhancements, anomaly corrections, and known
> issues for the current release or service pack. I would prefer to stick with
> this information and do away with the revision history, but maybe I'm
> missing something.
>
> Any opinions?
>
There are some variations, but many open source software products have a
more-or-less standard set of files in a top-level directory. e.g. For
FreeS/WAN (http://www.freeswan.org/doc.html) we have:
README, INSTALL, CREDITS, CHANGES, BUGS and COPYING
These cover:
README basic info: release number, where files and docs are
INSTALL experts-only quick install guide; most readers are
referred to more detailed HTML docs
CREDITS team members and other contributors
CHANGES revision history, all the way back to 0.8 in 1997
BUGS known bugs, and workarounds for them
COPYING license
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY. http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.
Sponsored by an
anonymous satisfied subscriber since 1994.
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
