[Mono-docs-list] RE: "Start here" mono documentation - mono Redbook?

Norman Lorrain normanlorrain@telusplanet.net
Mon, 16 Dec 2002 16:39:13 -0700


> I was wondering if you're working on it right now or want to start
working
> on it ?

Mono-docs seems very quiet.  Nobody else replied to my posting, so I
haven't bothered to start anything yet.  I'm still definitely
interested, so yes, let's try to put something together and see if
others accept it.

I'll return the introduction:  I have 10 years experience in C/C++,
mostly on MS platform but also some on Linux, QNX, and HP/UX.  I live in
Red Deer, Canada.  I'm new to C#/.NET, so I think a great way to learn
would be to make a contribution to the documentation project.

I like Ximian's pragmatic acceptance of .NET and I think they're on the
right track.  However, .NET is so huge that I'm sure even experienced
developers don't know where to begin. (heaven knows I didn't)  

To address this I was envisioning two items:
1. A high-level architectural overview of Mono.  This would include a
block diagram describing the relationship between C#, the class library,
the underlying OS, etc; (I want to describe the system-level context).

2. A series of tutorials which would be organized into different levels
of .NET proficiency.  I like working examples that lead a developer
along.
There could even be a roadmap showing the organization of the tutorials.
Perhaps they could be organized into themes or "paths".  Some Learning
Tree courses and Wrox Press books have this. (What I'm trying to do is
break this down into smaller and smaller pieces, so that the work can be
parceled out efficiently.)



Much of this information can be taken from the Microsoft MSDN web site
e.g.
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/netstar
t/html/sdkstart.asp
however, as someone interested in cross-platform development, I'm
worried that much of this may be specific to MS tools and platforms.
I'd like to see Mono have a truly independent documentation set.



> What about a MONO Redbook which includes the "start here" section ?

I'm not familiar with the IBM Redbooks.  I'll look at a couple to get an
idea.


 
> I (also) would like to pick up the existing idea of creating a
high-level
> document which is deep enough to get a developer up to speed. The post
(
>
http://lists.ximian.com/archives/public/mono-docs-list/2002-September/00
> 0102.html ) contains a table of contents. (are you using that TOC or
have
> you created another one?

That's a good start for a TOC.  I think section 1 corresponds to what I
mentioned in item 1 above.  The rest could be organized into the
independent tutorials I was thinking of.  I'm not sure we would gain
much with a C# tutorial, there are so many books and resources out
there( I'm currently reading the O'Reilly C# book), and I don't think MS
has extended standard C# yet (correct me if I'm wrong!).



> What about:
> 
> 1. Creating a table of contents for the "Start here" document/ MONO
> Redbook
> (if you don't have this al ready)
> 2. Analyzing all pieces of info all ready written and incorporating
> the docs which apply/belong in this document and do not have a certain
> place.
> 3. Refining and complementing the document.

That's an excellent plan. Before we start, what sort of format, or
framework, shall we use?  I'm leaning towards following the mono/doc
module in CVS.  It's got a script to build the web page, which is nice.
However I'm not sure how nicely it will scale as this grows; everything
is in one directory.  Also, we should accommodate different languages.
Any suggestions?


Cheers,

Norman Lorrain


---
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