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

[David Combs]

> From address@hidden Sun Jan 19 08:52:02 1997
> From: Al Gilman <address@hidden>
> 
> 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.
> 
<snip>
> 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. <snip>
<snip>

Have been reading an sgml book, and note that one can do
"conditionally assembly".  Presumably same is true for html.

Perhaps if CHANGES file were turned into an html file,
and each change could have two parts: one that described
what code changes were made and why, and one that described
for the USER what THAT person needed to know about it.

THEN it becomes FAR simpler to turn the changes file into
addendum for the MANUAL, via having html-parser expand only
the "for the user" parts.

Yes, is more work now, but perhaps "infinitely" less work later --
being that currently lots of this stuff NEVER gets into the
user manual.

To make it somewhat easier, perhaps there could be a standard
skeleton change-document-chapter or section or whatever for
ONE change, which has the html-notation already written in,
and then the lynx-changer merely ("merely", right) sucks in
that ascii "form" into his editor, and as he makes changes, etc,
fills in documentation in the appropriate areas of this html
piece of text.

One benefit would be to make the change-doc of various people
and times adhere to some kind of standard, again the purpose
being to semi-automate producing new documentation (or at least
addenda to the doc).  Crude, maybe, but MUCH better than no
user-doc at all, or making the user read through code-changes
and change-files DESCRIBING code-changes.

(They always say that the cobblers children have no shoes --
same seems universally true about programmers, even programmers
of html-parsers, not automating the production of documentation!)


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