[Mono-docs-list] Mono Documentation.

[Norman Lorrain]

Lots of interesting discussion going on here, so I'll touch on several
points in a single posting:

Regarding docbook:  I agree with Miguel that it's painful to setup and
presents a barrier to new contributors.  However for a project of this
scale it seems to me that docbook provides a means to enforce a
"standard" that keeps all the pieces of documentation consistent.  This
is already becoming important, as more and more contributors are
volunteering their efforts, and others are suggesting merging/linking
previously completed works.

For developers new to Mono, such as myself, consistent documentation
goes a long way to giving confidence that things are relatively stable
and that it's worth reading.

If someone wants to take the role of documentation formatter, to ensure
this consistency, then lets go ahead and work in HTML.  The first task
for this person should be to set up the Table of Contents in CVS.  (btw,
I'm for calling the module mono_guide or mono_manual.  Let's save the
term tutorial for individual, targeted topics e.g. Gtk# Tutorial,
Windows.Forms Tutorial)  The TOC could easily accommodate a section for
tutorials, in fact these could go in the later chapters.



Regarding Microsoft documentation:  One of the questions I have as I
approach Mono is - where do Mono and MS .NET differ?  To address that, I
don't think it's necessarily bad to have _some_ duplicated
documentation.  Where there are absolutely identical interfaces and
behaviour between the two technologies, I don't have a problem simply
linking to MSDN or other sites.


Merry Christmas!

Norman Lorrain
 

---
Outgoing mail is certified Virus Free.
Checked by AVG anti-virus system (http://www.grisoft.com).
Version: 6.0.431 / Virus Database: 242 - Release Date: 17/12/2002