[Mono-docs-list] Re: A first draft table of contents for the 'Start here' monodocumentation, comments please

[Felix Faassen]

Hi guys,

Thanks for your input. Let me stress out something. Yes, this TOC has an
overlap with the
tutorial created by Martin. It's not my intention to have this document
replace the tutorial in anyway!
Instead I think both documents should be complementary.

The way I see it is that we should have a main document which describes
things at overview/high level
it should allow somebody to get a grasp of Mono, in a central place.

For the really in-depth usage I thought redirecting readers of the manual
to a specific tutorial which
has a more pragmatic and in-depth focus on the topic. I think PART 1
trough PART 3 should be  part of the

manual. Part 4 could be realized in two ways:

1. Part 4 will be a part of the manual and only describes functionality on
a high level and some guidelines
   Advanced topics like a tutorial how to use the Dataset object to reader
write XML files should typically
   be a tutorial thing.

2. Leave out Part 4 completly and incorperate it completly in the tutorial

Just to give you an example:

in CHAPTER 13 GUI programming, we would typically try to explain that the
GUI models on Windows and unix based

platforms differ, and what considerations a developer should make in order
to create cross platform
applications using Mono. To actually get something done we'll refer to a
specific (or part in) the tuturial

which focusses more on the HOW part. So giving examples of buttons,
controls sample codes, guidelines, do's and dont's etc. etc. (as I've seen
in the GTK# part in Martin's tutorial)

If I could choose, I'll choose option 1. Let part 4 exist in the manual,
keep it high level and refer to the mono tutorial to get examples on HOW
to do it.

What do you think?


To be extra clear, this TOC is just for creating a starting point. I'm
sure when we're working on it together
the toc will change  ;-)

I don't wat to get premature but my goal is to present a document
framework (the toc is initial in order to start with something), and a
document describing that framework to the mono project maintainers.
If everybody agrees on it when then could have some CVS repository
containing our base document perhaps, and start writing.

In this way everybody can submit there work to the manual. My feeling says
we should work very closely on it

together.Martin has obviously al ready created a lot of documentation on
certain subjects.
I also noticed that there are some "Beginners"HOWTO's created by Hinne
Hettema and Jaime Anguiano Olarra.
Are these in development right now? These document also provide very good
information.

I looked more into DocBook, and I'm convinced that it's the prefered way.
The linux documentation project
also uses docbook for there documentation. Once in DocBook and you can
publish it in virtually every way
HTML, PDF, MAN... etc. etc.


Okay I'll merge the comments from Norman into TOC. I'll present a new TOC
soon. I'll also try to get some more info from more experienced docbook
users how to start organizing a framework so that we can work on one
document together. If anybody on the list has experience with that, please
let me know.


Take Care,


Felix


Martin Willemoes Hansen zei:
>
> I think we have a bit of overlap between this manual and the gnome.net
> tutorial.
> Have you guys read the java tutorial? That was one of my inspirations
> for the gnome.net tutorial original the mono tutorial.
>
> What do you think of a merge (renaming gnome.net tutorial --> mono
> tutorial? or a split, like only keeping gnome stuff in the gnome.net
> tutorial.
>
> If it was merged it would be a complete first place to go to program
> with mono on linux/gnome or maybe pragmatic programming with
> win32/mac/linux on gnome, qt, win32.
>
> But with a clear split, so we have generel stuff first, then a win32
> section a linux section a gnome section etc. Could be nice for people
> only working on one platform and know it good. Also for the documenter,
> he can concentrate on the specific section he know.
> --
> Martin Willemoes Hansen
>
> --------------------------------------------------------
> E-Mail	mwh@sysrq.dk	Website	mwh.sysrq.dk
> IRC     MWH, freenode.net
> --------------------------------------------------------
>
>
> _______________________________________________
> Mono-docs-list maillist  -  Mono-docs-list@ximian.com
> http://lists.ximian.com/mailman/listinfo/mono-docs-list
>