Re: linux-kernel-documentation, proposal

[Douglas Gilbert]

Andre wrote:
> On Tue, 27 Jun 2000, Alan Cox wrote:
>
> > > Would a "[e-mail]" be the best model?
> > 
> > Probably initially
>
> Suggestions on the approach?
>
> > Each to his own goals. I want to be able to type 'make book' 
> > and get a book
> > that I can hand to anyone wanting to do Linux drivers 8)
>
> Sheesh, you always have the bigger picture in mind.
> Now I know why you say so little in person, you mouth is in a NOP because
> the brain is always inserting requests at the top of the list_head.
> 
> Given the grander scheme that you are putting forward, this does really
> lend its hand to technical writers talnet.  Have a writer to document
> changes as the happen would allow for the fastest and more fluid records
> about the latest and greatest toys.
>
> Comments,

Well yes we need up-to-date driver level documentation. Not just
for would be driver developers but also for people who want to 
use these drivers (i.e. base applications on them). However, I 
don't see any easy way for the guilty parties behind the code 
from escaping some documentation responsibilities. Perhaps they 
could write in their own language and then vet the translation.

Anyway, some good work has been done in the Documentation/DocBook
directory which is what I believe Alan was alluding to. If people
want to try the sgml/docbook route then I found Tim Waugh very
knowledgeable. He helped me produce this document describing
the SCSI subsystem in lk 2.4:
http://www.torque.net/scsi/linux_scsi_24/

Doug Gilbert
a linux scsi/sg bloke