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

[Ben Maurer]

On Thu, 2005-09-29 at 22:32 -0400, Miguel de Icaza wrote:
> Hello,
> 
> > 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)?
> 
> We are giving them stubs, because stubs are better than nothing, at
> least you get an idea of what is available, the types of the arguments
> and the return values.
> 
> Sure, it would be best to have full documentation, but this is not bad.
> Its a graphical "monop", which as Visual Studio has shown, it is useful
> to have *anyways*.

Of course; I've never disputed this.

> Now, if we can go from there to contributions, that is even better.

Given the historic rate of contributed docs (especially non-gtk# docs),
that seems like a pretty big "if". What reason do we have to expect that
there will be a large change from the status quo in this area?

> We as a project need to produce a full stack of open documentation, and
> our tools reflect this need and that is why we have a Wiki-like setup.  

Yes, we do.

> Your tool is already available, feel free to improve it, but it is
> merely an improved online browser, it is not an offline browser and it

Sure, if we added it to monodoc we'd need to make sure it behaved
cleanly with no network connection. NetworkManager :-)

> is not encouraging our community to use the Wiki feature to create real
> open documentation.

I don't see that this needs to be the case. What if we injected the text
"this method is only subbed out in Mono's documentation. Help us out!"
in msdn pages. The fact that we don't get alot of contributions suggests
one of two things: 1) we don't have many users because they don't find
the stubs useful compared to google. In this case, maybe my browser can
keep people in the monodoc gui, encouraging them to use the wiki
features 2) people are generally too lazy to contribute docs. I don't
think my browser affects this group in any way. They aren't going to
contribute docs. Period.

> As for convenience, its hard to beat Google for finding an API
> *anyways*, so people will resort to the Web anyways.

I'd love to see web searching added. I don't know if you noticed this,
but the .net sdk doc viewer in 2.0 does web searching. It looks in
community forums, sites like http://asp.net and on msdn, and combines
the results. Maybe we could use the google api and show results. If they
were on msdn.m.c we go to my doc browser.

To me, monodoc is the ideal place to put an msdn viewer. I do not want
to detract from the monodoc audience by pulling them to a different GUI
where there is no incentive to wiki what they find out from msdn.

Anyways, if this doesn't convince you that having msdn docs as an
additional form of documentation in monodoc is a Good Thing or at least
an OK Thing, I guess there's no use in debating this any more. But my
feeling is that worst case, the msdn browser will not affect the
frequency of wiki-style contributions and best case it will increase
them because people will choose monodoc over google.

-- Ben