[Mono-docs-list] [Take 2] Intended Audiance of Developer Resource Category?

[Adrien Dessemond]

[I am very sorry, I did a wrong manipulation in my webmail resulting in a 
  strange and unreadable garbage... I made corrections on the menu part in
this version ]


>> "Waltkthroughs"
>> > or "Howtos" that are typically available on the Microsoft
>> documentation.
>> >
>> > We are lacking a lot of these.
>>
>> Indeed but I believe we should first tackle the stuff that we already
>> have in
>> our wiki before creating new content.

Btw, how the API documentation synchronization is done vs contributions
posted though Monodoc ?

> Well, we could do those in parallel.
>
> We could use many Java and .NET walktroughs as samples, use those as
> references and just write the equivalent for Mono and Gtk#.

Miguel this is a great idea since they are the first resources new comers
will look for. I could have something concerning Glade# / Monodevelop.

When browsing through the Mono website I have noticed the following that
could be improved :

Pages are not homogenous. The small hiddable grey menu is a great idea
which  should be used especially on the "Use" page instead of the
"Resource frames" : Here we have links everywhere and some of them are
duplicated 2 or 3 times ("downloads" links). Very confusing.

With this menu, how about having a structure like this ?


Use

>From Mono

Mono is positioned to be.....

[Small grey hiddable menu (on the left or centered)]

1. Eating your first banana (the Monkeyguide)
2. Developer Resources
  2.1 API Reference
  2.2 Walktroughs and HOW-TO
  2.3 Mono internals
     2.3.1 Mono architectural design at a glance
     2.3.2 Languages specification
     2.3.3 Mono internals whitepapers
     2.3.4 Hacking Mono
     ....
  2.4 Application design
     2.4.1 Web applications and services
     2.4.2 Winforms / Gtk# / Cocoa# and others
     2.4.3 Integrating security features
     2.4.4 Porting application between Windows / Linux
     ....
3. Support
  3.1 Community support
    3.1.1 Project FAQ and Mailing-lists
    3.1.2 Known bugs / Bug report submission
  3.2 Getting commercial support
  ....

[/Small grey hiddable menu]

[Sections and content here]

The small grey menu should be on the left of the page (or centered on it)
but certainly not on the right. As english is read left-to-right, your
eyes and brain will follow that principle when looking at web page pages.
Making them jumping from one side to the other is the bad thing to do.

Guys, if we want to give an hard effort on the documentation to keep it at
a high level of quality and professionalism, I suggest to complete the
guidelines documents (having a complete Monodoc marks-up reference could
be great espcially on <block>). Providing document templates and examples
helps a lot too, especially for the API documentation.

For textual contents, I suggest to keep them as a trade off between a
short and concise form (which can be perceived as being "dry" by the
reader and leave him the impression that Mono is somewhat lightweight) and
a more meaty one.

Adrien