[Mono-docs-list] Manuals and Docs

Fri Apr 28 00:49:03 EDT 2006

Personally I would rather see a HUGE indexed and categorized how to
library on the mono project site related to everything about coding
with mono and mono implemented languages/libraries.  While googling
hits the lists, microsoft, and the code project etc, and usually
works, It would be a heck of allot easier to find stuff if it was all
in one place.  A categorized, beagle indexed, CD-ROM of that type of
concentrated mono content might be a nice add to a mono developer
network cd too  :)

The Gentoo (http://www.gentoo.org/doc/en/index.xml) project has
organically built up some some great docs, which I think has really
helped their popularity.  The core set is very structured and new user
friendly and is Handbook style, followed by reference style docs, then
by procedural HowTo style articles, followed by troubleshooting in
list archives and forums.    Could a similar type of setup work for
the mono site?

Slightly off topic:

Reading this was the first time I noticed that the go-mono.com site
was a wiki.  It doesn't seem like the "create account" function works.
 Is that by design?

http://www.mono-project.com/index.php?title=Special:Userlogin&returnto=Special:Userlogin

-n

On 4/27/06, Tony G <bd3sqkn02 at sneakemail.com> wrote:
> 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  -  Mono-docs-list at lists.ximian.com
> http://lists.ximian.com/mailman/listinfo/mono-docs-list
>