RE: Manuals and Docs

I agree with your observations.  A couple books help newcomers to Mono:
"Mono Kick Start" and "Mono Developer Handbook" (my personal favorite)

The problem with those books is that they try to educate people about C# at
the same time as they educate about Mono, so the Mono nuances get lost
amidst pages of general info.  I understand that a lot of people come to
Mono with no knowledge of C#, but there are hundreds of books on C# and
only two about Mono, so I wish the Mono-specific books would be more
focused on what the other books don't include.

Relevant to your notes, yes, there should be web pages with very specific
HowTo's about getting started, what commands and options are available,
etc.  Class library documentation is of course required as _reference_
material.  But you're talking about tutorials with a procedural approach to
solving problems, not syntactical details for someone who already knows
what tools to use.  We need more of thse HowTo "cookbook" documents.

There is some room here as I described above for a cross-over, where HowTo
do something in Mono is procedurally exactly the same as doing it with
Microsoft C#, so duplicating this sort of effort in the name of providing
data about Mono should be avoided.  We can go to CodeProject or other sites
for info like that.  The HowTo info at go-mono.com should be limited to how
to do things when the approach or commands are uniquely different than with
Microsoft C#.

The sort of material I would like to see more on includes:
- Installation: Yes, there are lots of docs about this, but most of them
are old and none of them explain how to handle issues when something goes
wrong.  Installations rarely are done in "sterile" environments, we use our
systems for other purposes, and let's face it, Mono installs frequently
break for various reasons.  More information would be helpful about what
files go where, why, and how to install files into different locations if
required so that they can be found by Mono when required.
- Understanding Mono Dependencies: (related to above) While this is a Linux
topic, understanding how Mono is built is critical for getting people to
use it for development and deployment.  This is not about how to install,
it's about where files are installed and how they inter-relate.  Many
people come to Mono from Windows, not Linux.  I see a lot of Linux-bias in
Mono development which assumes that everyone who uses Mono understands the
build process (for Mono itself and for individual projects) - this is a
mistake because it alienates people coming to Mono/Linux/OSS from Windows.
- Installation and use of SharpDevelop or MonoDevelop: I think it's
important that new Mono developers have a GUI IDE available to kick start
their efforts.  From there they can go back to the command line or use
other tools.  MonoDevelop is a nightmare to install due to its
dependencies.
- Effective use of Eclipse with Mono: Eclipse is a mainstream/accepted IDE
and if people can get started with Mono quickly using Eclipse we will see
more people adopting Mono sooner.
- Installation and use of XSP: There are many pages about this but people
need to do a lot of hunting to find it.  It would be nice to have an entire
section of web pages dedicated to nothing but XSP, and even Mono web
development for people who are more familiar with the ASP.NET model.
- Introduction to GTK# with Mono - Yes, there are many pages like this too,
but it would be good to see them all in one place, with a focus on very
specific GUI features and how they are implemented with GTK#.  Examples
include menus, tabs, various controls like radio buttons or grids, how to
implement progress bars, trees, etc.  The examples should focus not just on
code but how to build a GUI with specific tools like MonoDevelop, how to
place controls, debug, handle events, etc.

I'm not sure how many people agree with this approach.  I only wish I had
the time and skills to write info like this.

Regards,
Tony

Gilles Fabio wrote:
> Hello everyone!
> 
> My name is Gilles, I'm 23 years-old and I actually live in France (I'm
> going to move to Australia pretty soon). I'm a Mono Lover. Thanks to
> the team and contributors for all your work.
> 
> Well, it's just my point of view. I really don't like the structure of
> the official website concerning documentation. Imagine I'm a newbie. I
> downloaded Mono and I would like to program my first application to
> understand how Mono works. I click on "Manuals and docs" in the top
> right and boom! I have before my eyes an "expert" documentation. I'm
> just a newbie! Wow! Too many libraries! It's really cool but I'm lost!
> I know that I can program a GUI application with Gtk# but how to do?
> If I click on "Gnome Libraries" and "Gtk", I find tones of classes but
> I absolutely don't know how to use them. So, I return to the main page
> and the only one link which sounds good to me is "Articles". I click
> on this link and on the Articles page, titles are organized by date of
> publication. It's not coherent. It would be better to organize
> articles by domain of application. The Article link on the main page
> is like "it's kind of something not important" but it's really
> important! So, that's what I propose.
> 
> (1) When we click on "Manuals and docs", we go to the page "Manuals
> and docs" (2) On the top right of this page, a link to the API doc
> (http://www.go-mono.com/docs/).
> (3) On the top left of this page, a link to the Monkeyguide
> (4) In the content section of this page, articles organized by domain
> of application
> 
> I think It's more coherent and newbies won't be lost.
> 
> It was the first point. Now, the second point: translations.
> 
> It would be really good to propose articles/howtos translations
> directly on the website just after the article/howto link, so like
> this: "Hello World!" in Gtk# [english - spanish - french] and inciting
> people to contribute directly on the website. So like that, when
> someone will want to write an article/howto on their personal
> website/project, they just will have to check if the article already
> exists and why not to officially link their article/howto in this
> section if it doesn't talk about an existing subject yet.
> 
> Voila :) I say it again, it's only my point of view so very
> subjective. I'm ready to contribute if you wish.
> 
> Regards,
> Gilles


_______________________________________________
Mono-docs-list maillist  -  [email protected]
http://lists.ximian.com/mailman/listinfo/mono-docs-list