Re: Documentation

[Hiten Pandya <hmp@xxxxxxxxxxxxx>]

Jeroen Ruigrok/asmodai wrote:
> Good programmers do not necessarily make good documentation people.

That is very dependant on a person's mentality than whether he is a 
programmer or not.  I don't mean to suck up or blow wind up anyone's arse 
but I have not had problem with docs that Matt has written, or PHK for 
that matter.

I agree with Simon that it is very important that we enforce people into 
writing atleast a stub manual page for added functionality and work with a 
documentation person to get it polished and finished off.

> And officially authorized...  I dislike these kind of practise.  This
> remains a volunteer project and you can whine all you want but for me it
> will remain on a voluntarily basis, including documentation.  And no amount
> of pressure will make me work harder and that goes for more people.  Sorry,
> I don't see that working at all.

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.

All forms of documentation should be kept up to date.

Just because it is a volunteer/open-source project does not mean you 
should not follow guidelines.  If you are going to contribute/write 
something that will make significant impact to the OS, you need to provide 
documentation.

As for whether the idea will work or not, we can only know after we try 
the idea. :-)

> > - create a src/CHANGES, in which commiters need to record major changes
> > to the system (so no small bugfixes, but for example "Imported OpenSSL
> > 0.9.8, a feature release").

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.

Hiten