[Mono-docs-list] Organizing docs, DocBook?

[Norman Lorrain]

Felix,
I agree with what you're saying.  To summarise:
- Class Library documentation (API docs)
	We will simply point to it.  Automatically generated by the
developers
	documentation

- Manual based documentation 
	The focus of our effort.  I like manuals because, even by
skimming the 	table of contents, you get a feel for how big the system
is, and the
	importance of a topic is evident by it's prominence in the text.

 
- Referenced based documentation (FAQS, HOWTO's TUTORIALS)
	We should definitely keep the faq, and point to it; everyone
	expects there to be one.
	Tutorials can be pointed to by links in relevant sections of the
manual.  As new tutorials get written, we can simply add links.
	There can also be a master list of Howto's/tutorials; that would
in 
	effect create a "cookbook" like Perl/Python has (O'Reilly).


Regarding the docbook, let's look at some example documentation from
other projects.  I'm a fan of Postgresql, and noticed on their online
doc's 
http://www2.ca.postgresql.org/users-lounge/docs/7.2/postgres/

that they use docbook as well:
http://www2.ca.postgresql.org/users-lounge/docs/7.2/postgres/docguide.ht
ml


I've heard about docbook, and would like to try it out.  It seems very
appropriate for what we're doing.  If someone with more knowledge wants
to advise against it, please do!  Hopefully it won't prevent us from
linking to the class documents and tutorials.  I'd also like to see some
diagrams (pictures are worth a thousand words!), and I don't know if
that's possible with docbook.





> As for now I understand there 3 types of categories when it comes to
the
> documentation:
...
> * Documentation system/format
> Okay enough ideas. I'm working on the TOC, as soon as it's finished
I'll
> post it here. I also start to look into creating a docbook. Any
> suggestions
> about the docbook issue?
> 
...


---
Outgoing mail is certified Virus Free.
Checked by AVG anti-virus system (http://www.grisoft.com).
Version: 6.0.427 / Virus Database: 240 - Release Date: 12/06/02