Re: Release notes and readme files

Subject: Re: Release notes and readme files
From: Joe Malin <jmalin -at- jmalin -dot- com>
To: John Posada <jposada01 -at- yahoo -dot- com>
Date: Sun, 22 Oct 2006 19:59:30 -0700

I also find that the requirement for Release Notes/readmes/etc varies
with the audience.

I would not put important information in a readme or Release Note for
commercial consumer software that otherwise had a manual, since I would
not expect the customer to read it. I also wouldn't release a list of
known bugs, since the customer might misinterpret it.

I worked at Oracle before, and we *always* released a list of known bugs
and fixed bugs. That way, our customers would know if a release was safe
to put on their system. They also knew if it fixed a particular problem
they were having. I did expect these customers to read the Release
Notes. We used Release Notes for information that applied to a very
small subclass of customers using special platforms, special
combinations of products, and so forth.

Having worked in just about every software environment you can think of
(and some you *can't*), I always browse through all the documentation
and the readme/release notes/install files before I start out. Of
course, I also register just about everything I buy; I was in marketing
once, so I know how much time, effort, and money people put into
registration.

As for bugs versus features, that's been around forever. I have
somewhere a cartoon; it's divided into two panels. The first panel shows
a cockroach-like thing, and underneath it the caption "Bug". The next
panel shows the same cockroach, but this one is wearing what looks like
a formal dinner jacket with tails (and multiple arms). The caption, of
course, is "Feature". This thinking is endemic to the software biz; my
friends know that I will criticize a particularly egregious, silly, or
otherwise outrageous problem with the sardonic comment: "It's a feature."

Joe

John Posada wrote:
>> "According to most of the development people I've worked with,
>> there is no such thing as a bug. It's just an undocumented
>> feature."
>>
>
> I've never had a developer say this without smiling afterwards. A
> developer knows a bug when they see one.
>
> Back to the question...
>
> The difference between a Release Note and a readme is timing. A
> Release Note is a fully formed and formatted book containing Known
> Issues, Enhancements, and Fixes since the last release, and a readme
> is a text file containing everything that was discovered but was too
> late to get into any of the documentation.
>
>
>
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today! http://www.webworks.com/techwr-l

Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


References:
Re: Release notes and readme files: From: John Posada

Previous by Author: Re: Showing sample and proprietary content
Next by Author: Re: FrameMaker mis-using paragraph fonts
Previous by Thread: Re: Release notes and readme files
Next by Thread: Re: Release notes and readme files


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


Sponsored Ads