documentation effort

[Khaled Daham]

> > How did DocBook fail one of the above criteria ?
> > IMHO DocBook is the most generic and complete set that someone can pick up
> > regardless of OS preference, packages exists etc.
> 
> It's HUGE.  It fails #1 and #5.  If an author spends more time restructuring
> and researching, than writing, we lose.

Sure it is huge, but I would not say I spend alot of time on researching
when writing my technical sgml documentation in docbook. There are some
good tutorials there for example the FreeBSD documentation project
guidelines.

> Don't be confused by having ``debian'' in the title.  I'm not evan-
> gelizing.  The only thing that is bourne out of Debian is a 60-line SGML
> DTD.  The rest of what I mentioned is SGML processors and rendering tools
> (tex, e.g.).

No I do not think you where being evangelistic, its just that those extra
perl modules and another DTD file instead of the common docbook might not
be worth it. 

Is the DTD easily downloadable somewhere ?

> > Maybe something like how PostgreSQL have divided the docs.
> > 
> > Tutorial <- simple a-couple-of-brain-dead steps to have it running
> > Admin <- more in-depth explaining.
> > Developer <- explaining the module setup and inner stuff.
> 
> I haven't even considered 'Developer' yet.  I don't think it's needed,
> IMO; we're much smaller than PostgreSQL.
> 
> 						- chad

That is true, though more than once have questions risen on -users about
how to add a module or change this and that ( each time being answered by
"look at the source" )
It would also make the project look more professional.

ps. I am glad though that this issue is being discussed at all, I atleast
think the current documentation sucks .ds

/Khaled Daham, w.arts
Mail:    khaled@w-arts.com, khaled@telia.net
Cell:    +46-70-6785492
FreeBSD: The Power to Serve! http://www.FreeBSD.org/