Documentation

[Justin C. Sherrill]

On Wed, July 27, 2005 9:12 am, Hiten Pandya said:

> I like the idea of a person who will remind us about when we forget to
> document important and feature-full changes.  Although I was the person
> who imported and flashed the handbook in the first place, Justin tried his
> best to keep it up to date but single-handedly he is having issues.
>

Changing jobs and homes killed my productivity more than I thought it
would.  Guidelines would be helpful just because it may make it easier for
people to start documenting material.  Right now, you have to be familiar
with the existing framework to do much other than minor updates.

> I think an src/CHANGES file, similar to NetBSD (I think) should be good,
> maybe something in ChangeLog format? :-)
>
> On that note, we also need a file that will describe and set time on APIs
> or utilities/programs/programming-practices that we will be deprecating by
> release X.

Explicitly saying what changes (like the above) need to be mentioned will
help a lot.  The recent pam.conf changes, for instance - how would someone
know about that, unless they watch cvs logs.  It'll make release notes for
1.4 a lot easier to create.