Re: Intended Audiance of Developer Resource Category?

Hello,

On Thursday 17 May 2007 04:06, Adrien Dessemond wrote:
> Hello!
>
> This is good idea ! The pit to not fall into is to have a too
> complicated structure at the end (the MSDN library suffers of that).

I believe that Mono won't fall in such a pit because, it is not as large as 
the MSDN, we simply do not have that much content to structure into 
uncountable categories. But still that's something we have to keep in mind.

> Beyond your suggestion, could I express a more personal point of
> view  ? I apologize if was previously discussed and/or conflict with
> some project orientations. I am curious to get some feedback about it
> and by the way, may it will bring some ideas too.
>
> <personal point of view>
>
> I am following (from a far away point of view) the Mono project for
> more than 2 years and started to seriously use Mono for a personal
> project a couple a weeks ago. Because writing and dealing with
> documentation is my everyday job, I was led to the following reflection :

Glad to hear that a person who has experience in dealing with documentation is 
interested in the Mono-Documentation Projects. Hopefully others will follow 
and it will gain a little bit momentum now. (It has been creeping for a 
looong time now...)

> My personal and professional experiences told me that even you have
> the most advanced/robust/complete/flexible product, it will rejected
> by some of your users if it does not have robust (clear/concise/....)
> and well-organized (logically organized / easily-browsable) documentation.
>
> To try to figure out my idea : imagine you are just curious to see
> what Mono is. You launch your favorite browser, you type
> www.mono-project.com in the URL bar et voila : the site has a very
> nice look-and feel, downloads/blogs links are easy to reach, general
> project information is easy to find and clear enough.
>
> Now come to site as a developper : you know what Mono is, you have
> dowloaded and installed it. You have precise goals in mind about your
> documentation search and no time to loose in guessing where the stuff
> could be. If you wish to get the right thing right now... not very easy
> :-(.

Concerning this I'm having another Idea. Recently I was thinking about of 
rewriting the Use-Page. At the moment it is just a list of tools that can be 
used but I'm thinking of rewriting it in a way that does not show what of 
mono can be used but in what way mono can be used.

For example:
Use case 1: Develop Cross Plattform Apps.
Use case 2: Develop Web Apps.
Use case 3: Port an App from Windows to Linux.
Use case 4: Embedd Mono into your App.
Use case 5: Something completely different.

Each of those use cases should contain a link to a page which summarizes the 
use case and gives hints and shortcuts how to achieve the goal. (Okay the 
last one should point to a place where for example research projects based on 
mono can publish what they've done so far and how they have achieved it...)

>  From my point of view, the developer related documentation will need
> a different approach sooner or later as Mono popularity, maturity and
> user base are growing. You cannot afford to keep it scattered on many
> pages with no clear linking and no easily browsable central point.
> That will be a nightmare to maintain, a pain to consult and a huge
> source of frustation.

I agree and believe that we are at this point right now.

> This new approach /could be/ a Wikipedia-like site but wholly
> dedicated to Mono. Several reasons :
>
> 1 - We are very familiar with Wikipedia so using (say) Monopedia will
> not require extra learning effort
> 2 - A wiki usage is natural especially for a developper and offers a
> high level a flexibility and diversity
> 3 - Monopedia could follow the same philosophy as Wikipedia :
> everyone can contribute freely in "real-time".

This is something where we have to be extremely carefull.
The class documentation for example has a user-documentation-submission 
system. But all submissions have to be checked for approval because users 
sometimes copy and paste stuff from the MSDN and we can not use this content.

> (3' - Writing and cross-referencing between articles is really simple)
> 4 - The wiki documentation grows by itself in the background and
> allow the Mono documentation team concentrate on other tasks.
>
> Do you think this kind of perspective could be compatible with the
> Mono documentation project (short/long term) ? I welcome any
> opinion/criticism :-)
>
> </personal point of view>
>
> Valentin, I would be very glad to help you and any Mono documentation
> project efforts in manner or another.

I and the whole Mono-Project are very thankfull for your contributions in this 
discussion. :-)

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