LYNX-DEV where the CHANGES file breaks down in documenting fixes

[Al Gilman]

Disclaimer:  I am not asking that something be done about this at
any particular time.  I just wanted to get this analysis on file
for whenever it seems a good time to do something about it.

In the CHANGES fragment quoted below, we have an example of a
link that doesn't quite work in our documentation practices.

  From: Foteos Macrides <address@hidden>
  Subject: LYNX-DEV v2.6FM update

  01-18-97
  [...]
  * Tweaks of the news/nntp/snews gateway. - FM

I believe, that these tweaks fix a problem which is associated
with symptoms Larry described in a post to lynx-dev.

Sometimes we have chided users who report a problem for which the
fix is already available as a patch (or via a rolling release
such as -FM).  "Read the CHANGES" they are advised.  Here is a
clear (but not unique) example where there is no clue in the
CHANGES record of the symptoms associated with the problem which
has been fixed.  In this case reading the CHANGES file will not
tell the user that their problem is old news and has already
been addressed.  A search of the lynx-dev posts is required to
find the record (which exists in the public view) of this fact.

An alternative CHANGES record which was an HTML document with
links to the archived post describing the symptoms the user sees
and the post announcing the fix would at least capture the
information that is now missing.

Clearly my un-FAQ is an example of a way to construct such a
record.  Set your bookmark file to an IN_WORK page and cache a
link to the problem statement when you start working on a
problem, and include these links in the CHANGES record when they
have been resolved.  So far I have been too lazy to try to follow
the changes as they go in and do this from afar.

This may not be the best way to do it, or worth the extra effort.
But there is a disconnect, here, and this is one possible way
to bridge it.

--
Al Gilman
;
; To UNSUBSCRIBE:  Send a mail message to address@hidden
;                  with "unsubscribe lynx-dev" (without the
;                  quotation marks) on a line by itself.
;