How to lend a hand to NDoc and other non-MS Developer Tools


I was forwarded an interesting suggestion today from the Product Feedback Center.  Here it is:


Put some developers on the open source nDoc project


We have used the XML documentation system with our C# code. Full integration with VS 2005 and .NET 2.0 is missing. Unfortunately, the developer for the open source nDoc project has not updated this project in some time. We do not have the resources nor knowledge base to offer our direct assistance to this project.


By time you read this my reply to the suggestion should have been propagated from our internal database to the feedback center.   But aside from the resource concern that’s real there are some interesting questions this raises.


I’m honestly don’t think there is consensus that it’s our (Developer Solutions) team charter to do development work on projects that were born out of the community.  We (Microsoft) really don’t like stepping on community toes and don’t want to be seen as taking over/invading 3rd party territory.  But are there other ways we could help out projects like nDoc?



  • What if we highlighted more projects like nDoc from our developer centers to get more attention that might lead to more community contribution?

  • What about having some sort of awards for shared/open source development in the Visual Studio developer tools space?

  • What if had some project sponsorships we could give out each year to developers who take on projects like this? 

Other ideas?

Comments (16)

  1. Tim says:

    I will say that i like all of your suggestions there in general for community projects. Any way that Microsoft can put the spotlight on projects like that is great.

    However, in the case of nDoc, i think the real issue at hand here is that Microsoft needs something like this built-in to Visual Studio (or as a PowerToy or something).

    VS2005 has added many tools for the developer so that it can be used across many of the phases of the development cycle. But one is still sorely missing – documentation. Sure, VS supports the XML comments for creating the documentation… that’s the basis for all this work afterall. But without nDoc, i either have to pay a lot of money to a company to make those xml files useful, or i have to roll my own. Which i dont like to do when i don’t have to.

    I definitely think this is one project that Microsoft should be more involved in. For others – i like the suggestions you have and i’m sure people will have more like them.

  2. leppie says:

    A combination of the last 2 sounds good. Like an MVOSS list. It should get people interested. Sponsorship is good if the funds can be distributed in a fair fashion, so that really works only on small projects/teams, and those are the hardest to find!

  3. tzagotta says:

    First, let’s get real – Microsoft as a whole has no qualms stepping on third-party toes. This may bother you personally, but MS has done this lots of times in the past.

    Second, I think that, in cases like this, it is actually beneficial to the customer for Microsoft to get involved. Adding this functionality into VS2005 adds value to that product and MSDN subscriptions. In this case, clearly there is a gap in that nDoc is not being actively supported enough by the communities to be updated, and I for one would love to see Microsoft get involved to help out, either by contributing to that project (which I think would be welcome by the community), by developing its own tool, or publishing an internal tool.

  4. Sean says:

    Yeah, what tzagotta said — lets not lose sight of the issue nDoc, is apparently important to a number of people — the capability to do XML documentation is supported by VS, but there’s no way to do anything with that XML documentation outside of having the summary tooltip.

  5. Haacked says:

    Microsoft could consider the approach that Collab.NET takes with Subversion. They’ve hired several developers to work on Subversion fulltime.

    However, these developers have to follow the same rules as any other developer in order to gain commit access. There is no special status given to them, they follow the same rules as other members of the community.

    I’m sure these various open source projects would welcome a full time resource from Microsoft who would contribute development efforts, as long as the developer worked within the group’s established charter and there is no expectation of special treatment.

    Also, remember that some of these projects are BSD licensed. Technically you could take the code, attribute the authors, and then modify the code and use it in any way you see fit, just as long as you follow the license.

    I have a series on that topic (http://haacked.com/category/32.aspx).

    Although I think the community would appreciate the first approach over the second.

  6. MSDNArchive says:

    Tim: What other solutions besides nDoc do you see people using in this space to convert the XML into real documentation?

    Leppie: Yeah, I struggle at figuring out how we would distribute funds fairly to which projects.

    tzagotta: Actually there are a lot of people that feel the way I do here about invading partner/community territory. Although I will admit that there is an interesting line… at what point do we stop taking suggestions and start saying "there’s an object model" for 3rd parties.

    Sean/Haacked: I’ll have to take a look at the nDoc license today myself.

  7. orcmid says:

    I had read recent coverage about nDoc and it somehow escaped me that there isn’t anything comparable wired into VS 2005. I haven’t got around learning the “///” annotations yet, although I am looking forward to it (and seeing how much works in the VS 2005 Express Editions).

    nDoc is under GPL, and I figure that is sticky for you folks. It certainly drops my interest a notch.

    But apart from those details, I like how you are looking at this. I wonder if there would be a tie-in with Code Camps or even Coding4Fun for some of these, although it sounds like Developer Solutions is probably the right level of effort if not the proper home.

    You might need a community voting system. The ProductFeedback engine looks adaptable to something like that. It’s turning out to be pretty slick, with the few glances I’ve given it.

    Bottom line: Great suggestions and questions. Keep going.

  8. Roy J. Salisbury says:

    About 2 years ago I was helping out with a PowerToy that you first released on GotDotNet that created help files out of the doc comments.  At the time, it was a great idea, and had a lot of potential.  However, It very quickly died for a few reasons:

    1) Lack of community support .. after all nDoc existed. Most everyone that joined the project just wanted the tool, and did not join to help in development.

    2) Installing the help into the MS help collections was a pain.  You had to modify the .msi files with Orca and is was just ugly to deal with.

    3) It was limited to C# since at the time VB had no code comments (although there was a PowerToy for that as well).

    4) VS2005 was in alpha/beta, and as with most of the PowerToy’s that MS releases, they end up in the product (usually much better than the community version).

    So, although some people like the idea of an nDoc type of help compilier built into the IDE, it’s not really that high up on the list of "need to have" items.

    Having said that, there has been a few major advances in the IDE from 2003 to 2005 that actaully make this an easier project now..

    1) WiX — Another Shared/Open source project that might make creating the .msi files easier.

    2) MSBUILD — Creating a task to actually assist in the creating of the .htm files that is needed would be much easier.

    3) VB now has a documented code comment standard.

    4) MSBUILD (again) — in VS 2003 is was common for the assmeblies to get locked during the build process when doing reflection to get a listing of types.  Not really a problem now that the IDE is not doing the build.

    5) The editor’s object model is a bit better (not much, but some). This may help in the parsing of the document comments for a better editor.

    So, perhaps the project on GotDotNet should be brought back to life and we could try this one in the community again?

    Josh — shoot me off an e-mail if you think this is worth discussing.

  9. MSDNArchive says:

    Roy: It’s probably worth talking about.  You make a lot of good points I hadn’t considered when looking at this project as an alternative solution.

  10. Kevin Downs says:

    As the main developer of NDoc 1.3 and the titular admin of the project, I thought I’d let you all know that NDoc is not dead. It is, to use an Australian reference, playing possum; alive but keeping very still so as not to attract too much attention!

    There is an *alpha* release of a new version of NDoc for the v2.0 framework, although this is not in general circulation.

    Originally I had planned to do a simple upgrade of NDoc 1.3, but this proved almost impossible. NDoc2 is, to all intents and purposes, a complete rewrite (a huge undertaking) and has taken far longer than I originally anticipated due to illness. I was forced to ‘go dark’ on this development because I was getting some fairly offensive emails *demanding* a new release, and I could not give a firm time-line due to the above mentioned illness.

    At present I am taking a few weeks off as my wife had a baby a couple of weeks ago 🙂

    I am planning to resume work soon, but in the meantime anyone interested can contact me at (kevin-at-kdowns-dot-com) add I will add them to my alpha testers mail list and direct them to where they can obtain a copy of the latest build…

    To address the main topic, MS has been helping with the new version all be it indirectly. I have exchanged many emails with MS staff who have been very helpfull in digging-out the obscure minitiae I needed to get some aspects working.  Far more importantly, I received one of the MSDN subscription invites that MS gave the MVPs (my sincere thanks to Oleg Tkachenko) – trying to build software of this scale is hard work using C# Express! 🙂

    Kevin

  11. Frank Hileman says:

    Hello Kevin,

    Just wanted to say NDoc is a wonderful tool, up there with the best commercial products, and you are a hero!

    Thanks!

  12. Neville Campbell says:

    Microsoft dropped the ball on the XML documentation system right from the beginning.  I don’t understand the reluctance to at least reach parity with JavaDoc.  The functionality should be included with Visual Studio.

  13. NDoc is a very useful open source project that generates reference documentation from .NET assemblies

  14. coldacid says:

    I can understand not wanting to step on the community’s toes, but when a project is abandoned, it doesn’t hurt to step up to the plate. With an open source project like NDoc the worst that will happen (beyond the immature nippings of a select crowd) is that people who don’t like your changes will fork the project. Either way, activity would return to it.

    It’s not an issue so much now that Sandcastle is publicly available, but for the next time a popular community project goes dark, having some support would be quite useful.