[Mono-docs-list] Intended Audiance of Developer ResourceCategory?

Adrien Dessemond adrien.dessemond at softhome.net
Fri May 18 17:41:39 EDT 2007


>> > Another thing that I find useful myself are the various
>> "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]

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 Mini internals whitepapers
     ....
  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
     2.4.5 Hacking Mono
     ....
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>> > Another thing that I find useful
myself are the various
>> "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]

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 Mini internals whitepapers
     ....
  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
     2.4.5 Hacking Mono
     ....
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
  ....

[/Small grey hiddable menu]

This 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 profesionalism, 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. If some one can
provide me the stuff I would be glad to complete the page.

For textual contents, I suggest to kee>> > Another thing that I find
useful myself are the various
>> "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 center)]

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 Mini internals whitepapers
     ....
  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
     2.4.5 Hacking Mono
     ....
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>> > Another thing that I find useful
myself are the various
>> "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]

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 Mini internals whitepapers
     ....
  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
     2.4.5 Hacking Mono
     ....
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
  ....

[/Small grey hiddable menu]

This 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 profesionalism, 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. If some one can
provide me the stuff I would be glad to complete the page.

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



More information about the Mono-docs-list mailing list