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

[Felix Faassen]

Hi Norman, Martin and others,

First of all let me say this, because I don't want to give the wrong
impression and I don't want to be cocky ;-)

These are just ideas I have in order to get to start working on the
documentation.
I just want to sort some things out before I'm going to spend time on
writing anything and I want to be sure there
aren't all ready people working on this.

So please see this post as "in my humble opinion" hehe, okay enough
disclaimers...


As for now I understand there 3 types of categories when it comes to the
documentation:

- Class Library documentation (API docs)

- Manual based documentation (Overview, Installation, Getting Started, MONO
Architecture,Tools, Resource etc.)

- Referenced based documentation (FAQS, HOWTO's TUTORIALS)


* Class Library Documentation
If I understand correctly there are tools currently in development in order
to facilitate
a documetation system in regards to the class libraries. This part is all
ready covered by the MONO DOC specs and supporting tools. I also read that
class contributors are submitting the documentation as well.

* Manual based documentation (Getting started/ Redbook/ Overiew etc.)
As for now I have not found any document which gives a complete overview on
MONO, which describes steps how
to install (win32/linux/etc) how to get started etc etc. There are some
FAQ's and tutorials which cover these
topics but I have yet not found a central document.

I think it's a good idea to create a general document which is considered a
manual to mono. This document should focus on
getting people started with mono and give them overview of what's out there
and how to use it. Furthermore it should
reference to other resources on the mono website and of course the tutorials
on. Norman and I had the idea of using the table of contents, posted earlier
on the docs-list and work out, we both make a TOC, post it and try to figure
out (together with other list subscribers) a general TOC so we have a tree
where we can write on ;-)


* Reference Based Documentation
I think it's a good idea to have the turorials seperate from the manual
based documentation, as we can now see on
http://go-mono.com/gnometutorial/. I generally like the tutorials which are
on http://samples.gotdotnet.com/quickstart/
or http://samples.gotdotnet.com/quickstart/howto/. Actually I just checked
it out and I'm confused, how do we call
this a HOWTO, tutorial or quickstart ;-) heheh doesn't matter I hope  you
get the idea


* Documentation system/format
I looked into the MonoDoc XML specs. Correct me if I'm wrong, but as written
on the mono site MonoDoc is the format for multilingual API documentation.

As I've written earlier I haven't got any experience with publishing
systems. But as I can see Docbook is the way to go, right? Martin what have
you used to create the tutorial?
(About this having no experience with publishing systems I'm working realy
hard to get a grip on DocBook)

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?


Take Care,


Felix