[Mono-docs-list] Re: msdn-browser/monodoc intergration

[Ben Maurer]

On Mon, 2005-09-19 at 16:53 +0200, Mario Sopena wrote:
> 2005/9/16, Rafael Ferreira <lists at ophion.org>:
> > yeah I see your point of view. But not having the documentation there
> > can also just lead to the user popping a browser and going to msdn
> > anyways, and by doing that he/she cannot add value to monodoc. Keeping
> > the user inside monodoc increases the chance of contributions. In any
> I'm not sure that is the case. I'm also more from the opinion of
> Joshua, as I told to BenM on IRC. I do think the documentation in mono
> is getting better but slowly, so we have to find ways to encourage
> people to write docs, and that addition to monodoc will send an
> ambiguous message to contributors

IMHO, this is a silly argument. First, we should not give our users
stubs for documentation because they might fill in the stubs. Second, if
a user is inspired to fill in the stubs, the first thing he is going to
need to do is to find the msdn docs for the same method so that he can
get some idea of what it does. So why not make this process easier, by
providing them a usable interface (IE, a treeview that doesn't suck in
firefox)?

Realistically, it is going to take us a long time to have docs that we
can really call a replacement for the msdn docs. Also, msdn has other
valuable content (for example, the articles, win32 api docs which can
come in handy for the IO layer, etc) besides the api docs.

> BTW, the msdn doc utility is incomplete, as you cannot click on the
> links (and it won't be easy to fix);

Shouldn't be all that hard. All I need to do is intercept the link click
from gecko, load it, and sync the toc, all of which are actually pretty
easy (there is data in the html pages for toc syncing).

>  so it needs a lot of work before
> being added.

IMHO, this tool is useful today even without any more features. It is
10x faster for me to use my tool than it is to use firefox.

>  Also, it is made with gtk#2 and we use gtk#1 in monodoc.

Miguel has talked about bumping monodoc up to depend on gtk#2. Once we
do this, I'd love to see the primary tree be moved to the new api. But
for now, I could live with another tab.

-- Ben