[Mono-docs-list] Re: msdn-browser/monodoc intergration
On Mon, 2005-09-19 at 16:53 +0200, Mario Sopena wrote: > 2005/9/16, Rafael Ferreira <[EMAIL PROTECTED]>: > > 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 ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
[Mono-docs-list] Re: msdn-browser/monodoc intergration
On Sat, 2005-09-24 at 11:25 +0200, Mario Sopena wrote: > 2005/9/24, Ben Maurer <[EMAIL PROTECTED]>: > > 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)? > The reason are what Joshua already said. If the user has a great doc > (msdn) at hand, they will just move to look there and not to use mono > docs, because what they care is having a good doc and not where that > doc come from (well, most part of the users). But that is just my > opinion. If the user is not willing to deal with the fact that our classlib docs has mostly stubs, they are going to end up using another documentation browser. For example, I usually use terminal server to a Windows computer to look up docs because I can use the .net doc browser. Now, lets say we integrate an msdn viewer. This will make it easy to get to the "good" docs. Thus, we will increase the use of monodoc. This has a huge side benefit: since people are inside monodoc, they can easily write docs for stubbed methods. We could even play on this fact; we could put a message on top of the msdn page for each member we have stubs "Mono's free documentation only has stubs for this method. Help us out by writing docs". We'd have to be careful not to encourge plagiarism with this, but I think it could help us rather than hurt us. I'd also like to remind you that most monodoc users (I'd guess upwards of 90%) do not contribute to the documentation, and there is almost nothing we can do to get them to do so (except maybe a bribe^Wcontest). not including a way to get to the msdn docs is just making their life harder, with no benefit to us. -- Ben ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Re: msdn-browser/monodoc intergration
Hello, 2005/9/24, Ben Maurer <[EMAIL PROTECTED]>: > 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)? The reason are what Joshua already said. If the user has a great doc (msdn) at hand, they will just move to look there and not to use mono docs, because what they care is having a good doc and not where that doc come from (well, most part of the users). But that is just my opinion. > > 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). I wast just not aware of the details. > > > 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. Hey, Ben, I think you took my email as an attack to the msnd doc, which is not. I think is a great tool, I was just wondering if it could have some negative effects including it on monodoc. Maybe it will be better to keep separate. But maybe I'm wrong. > > > 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. hey, I would like to be aware of that. I think that will solve a bug in elabel! Mario. ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Re: msdn-browser/monodoc intergration
On Sat, 2005-09-24 at 11:42 -0400, Ben Maurer wrote: > > I'd also like to remind you that most monodoc users (I'd guess upwards > of 90%) do not contribute to the documentation, and there is almost > nothing we can do to get them to do so (except maybe a bribe^Wcontest). > not including a way to get to the msdn docs is just making their life > harder, with no benefit to us. I'm sorry to go off on a small tangent, but we could be tougher when new code is written to get the original authors to document it, as unpopular as it may be. It has worked well for many other projects. Just like tests are required, some level of documentation also should be. ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Re: msdn-browser/monodoc intergration
My 2 cents: I agree 100% with Ben. The MSDN documentation is available and it is better than what we current can offer, period. Giving developers the best dev environment is the end goal here so making them jump through hoops to get to msdn is silly. As I've said before, embedding Ben's browser into a tab in monodoc (thus making the differentiation between doc sources clear to the user) if pretty doable and I would be willing to give it a try *if* Miguel gave the OK so I don't waste my time in a hack that would never see the light of day. - raf On Sat, 2005-09-24 at 11:42 -0400, Ben Maurer wrote: > On Sat, 2005-09-24 at 11:25 +0200, Mario Sopena wrote: > > 2005/9/24, Ben Maurer <[EMAIL PROTECTED]>: > > > 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)? > > The reason are what Joshua already said. If the user has a great doc > > (msdn) at hand, they will just move to look there and not to use mono > > docs, because what they care is having a good doc and not where that > > doc come from (well, most part of the users). But that is just my > > opinion. > > If the user is not willing to deal with the fact that our classlib docs > has mostly stubs, they are going to end up using another documentation > browser. For example, I usually use terminal server to a Windows > computer to look up docs because I can use the .net doc browser. > > Now, lets say we integrate an msdn viewer. This will make it easy to get > to the "good" docs. Thus, we will increase the use of monodoc. This has > a huge side benefit: since people are inside monodoc, they can easily > write docs for stubbed methods. We could even play on this fact; we > could put a message on top of the msdn page for each member we have > stubs "Mono's free documentation only has stubs for this method. Help us > out by writing docs". We'd have to be careful not to encourge plagiarism > with this, but I think it could help us rather than hurt us. > > I'd also like to remind you that most monodoc users (I'd guess upwards > of 90%) do not contribute to the documentation, and there is almost > nothing we can do to get them to do so (except maybe a bribe^Wcontest). > not including a way to get to the msdn docs is just making their life > harder, with no benefit to us. > > -- Ben > > > ___ > Mono-docs-list maillist - Mono-docs-list@lists.ximian.com > http://lists.ximian.com/mailman/listinfo/mono-docs-list > ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Re: msdn-browser/monodoc intergration
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*. Now, if we can go from there to contributions, that is even better. 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. 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 is not encouraging our community to use the Wiki feature to create real open documentation. As for convenience, its hard to beat Google for finding an API *anyways*, so people will resort to the Web anyways. Miguel. ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Re: msdn-browser/monodoc intergration
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 ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Re: msdn-browser/monodoc intergration
Hello, > 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 Wow, and encourage people to cut and paste the docs! Now, why didn't I think of that? So in short, no, I do not want to merge your browser with Monodoc (and there are many technical hurdles to fix before this could be done, but there is not even a point to discuss them). Miguel. ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Re: msdn-browser/monodoc intergration
Issue officially settled then :-) - raf On Fri, 2005-09-30 at 02:57 -0400, Miguel de Icaza wrote: > Hello, > > > 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 > > Wow, and encourage people to cut and paste the docs! Now, why didn't I > think of that? > > So in short, no, I do not want to merge your browser with Monodoc (and > there are many technical hurdles to fix before this could be done, but > there is not even a point to discuss them). > > Miguel. > ___ > Mono-docs-list maillist - Mono-docs-list@lists.ximian.com > http://lists.ximian.com/mailman/listinfo/mono-docs-list > ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
