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

[flixz@xs4all.nl]

Hi Norman,

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

GREAT!

>
> 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 think we can work something out, you obviously have a lot of developer
experience!

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

I agree. However I think the tutorial should focus on getting the
developer up to speed rather than giving him a comlete .NET C# sharp
course there are enough tutorials focussed on the C# language
fundamentals. (I see you've all ready said that later on in this post ;-)
)

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

I agree, I think the doc set should adhere to multi-platform environments.
I have to say I don't have that much experience with multi-platform
documentation systems. I think you have a good point that we should get
into the doc system of mono and see what it can do.

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

http://www.redbooks.ibm.com/, but I think you all ready found it :)

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

What about both creating a TOC for the Redbook (just in plain old ASCII),
after that we have something which we can tweak together etc. Then we
create one leading TOC together which we can post in the group to see how
people feel about it. And at the same time we could investigate how the
doc system works and if it's sufficient for creating the redbook.

About the multi-langual stuff, I think we should see if the doc system can
provide us with that, my feeling says it's something to worry about later,
but I do think it's a very good point and should be considered during the
complete process. Luckilly the docs are in XML so It's not such a huge
problem to adapt to other/future document systems/file formats ;-)

About language, as you can probably see English is not my mother language,
so I would very much appreciate any corrections during the documentation.

Norman nice to meet you and I'll start thinking about a TOC and look into
the doc system. As soon I have a reasonable TOC I'll mail it to you and
post it on the list.

Take care,


Felix

ps: Where should I CC your mail on teleusplanet or hotmail account?