http://blogs.clariusconsulting.net/kzu

Daniel Cazzulino's Blog

Go Back to
kzu′s Latest post

Improving the state of the art in API documentation sites

Go straight to the site if you want: http://nudoq.org. You can then come back and continue reading :)

Compare some of the most popular NuGet packages API documentation sites:

You see the pattern? Huge navigation tree views, static content with no comments/community content, very hard (if not impossible) to search/filter, etc.

These are the product of automated tools that have been developed years ago, in a time where CHM help files were common and even expected from libraries. Nowadays, most of the top packages in NuGet.org don’t even provide an online documentation site at all: it’s such a hassle for such a crappy user experience in the end!

Good news is that it doesn’t have to be that way.

Introducing NuDoq

A lot has changed since those early days of .NET. We now have NuGet packages and the awesome channel that is http://nuget.org. We can certainly do better!

Here’s an explanation of what it is, straight from the site’s home page:


TL;DR

  • Fast indexing and quick search (tree views are so 90′s!)
  • Community involvement via discussions and wiki-style content contributions
  • Automatically updated from NuGet.org packages (ALL of them!)
  • Automatic grouping of packages by project and cross linking
  • Offline support: just download a zip file!

NuDoq provides the missing link between straightforward access and updates to NuGet packages, and their corresponding API documentation. If you’re familiar with tools like Sandcastle and NDoc, they were built for an entirely different era: that of static documentation, with no community involvement, no peer-to-peer support, no frequently updated packages!

With all of the new shiny technologies available at our disposal, why limit ourselves to 90′s looking documentation sites, with no built-in search or filter, with endless tree views that take forever to navigate, and so on?

In short, NuDoq is:

Socialized API documentation for the XXI century

Community

We know how much better community-driven content can be, compared to the official documentation on pretty much every open source project. The rich discussions among actual users of a feature, their tips and tricks, and innovative usage of a library. All of that is sometimes even more important than the actual API documentation itself.

NuDoq embraces the community by including a Disqus thread for every page of content (i.e. project landing page, package, assembly, namespace and all public members), as well as a wiki-style section of content that can be edited by anyone with a GitHub account.

Feedback

We want to make NuDoq the best API documentation platform ever and we value immensely your feedback on how to make it better. We’d love to hear your ideas, bugs or comments on our feedback forums .

If you want to leverage the platform for your own privately hosted NuGet feeds, contact us.

Why NuGet?

NuGet is quickly becoming the de-facto distribution mechanism for libraries for all things .NET, and not just for Windows. Even the.NET framework has started to move towards more fine-grained packages that will be delivered via NuGet.org.

So why not leverage the tremendous potential of having centralized repositories of most (eventually all?) packages to build a unified API documentation layer on top?

One of the key benefits of using NuGet to drive the API documentation site is that NuDoq can provide

Automatically updated API documentation when NuGet packages are published

So now the same XML documentation that’s shipped with NuGet packages to drive intellisense tooltips within the IDE, is used to drive a corresponding site, automatically and seamlessly.

How it works

We regularly poll NuGet.org for the latest package updates, unpack and process the library documentation files, and update the site accordingly.

To improve the searching experience, we group packages by project, like Autofac. This allows you to easily and quickly locate the documentation and associated discussions.

If you’re a project author and want to tune the way we group your packages or make any other suggestions, feel free to contact us.

 

Yes, this might have just been a hugely overkill solution to Moq’s lack of an API documentation site, but it surely was fun and I hope you find it useful too!

Comments

10 Comments

  1. Hi Daniel,

    I’m really excited by this project. I’ve just started adding Sandcastle doco to a NuGet package and this is a much better outcome. I have a couple of questions though. It seems like not all packages appear in NuDoq. What is the filter applied by NuDoq that determines whether packages are processed?

    SgmlReader for example doesn’t come up. It doesn’t have an associated xml file in the package, but community editing of pages for the package could still be of use.

    My pre-release package also doesn’t come up. Does NuDoq only work with released packages?

    Cheers,

    Rory

    • Hi Rory,

      We’re processing all packages but the main reasons for the missing packages are 2 right now:

      1. No xml documentation files were found => So there is no “documentation” to generate. I think that the best way to fix this item is to ask the author/owner of the nuget package to provide the documentation instead of generating an empty topic in NuDoq.

      2. We could not load the assemblies. We’re merging the reflection metadata with the documentation files (and resolving and loading the dependencies of the package). However there are some packages that we are not being able to process right because we’re not being able to load the lib assemblies. We will try to fix these cases in the next few weeks.

      And I think we’re not including pre-release versions. But probable we should.

      Thanks for the feedback!

  2. Maybe we should add a warning at the project page level about the packages that we failed to process or didn’t have xml doc?

  3. Hi Daniel,

    i agree with kzu we should add the warning at the project page level.

    Thanks

  4. [...] Improving the state of the art in API documentation sites – Daniel Cazzulino shares NuDoq an new framework for creating documentation for the libraries contained in NuGet packages, providing baked in support for working with NuGet packages, fast indexing and searching, community discussions and contributed documentation via a Wiki interface [...]

  5. Could you file that as a suggestion on nudoq.uservoice.com please?

    Thanks for the feedback!

  6. [...] Improving the state of the art in API documentation sites (Daniel Cazzulino) [...]

  7. [...] Improving the state of the art in API documentation sites by Daniel Cazzulino Details on the motivation behind NuDoq: a website for API documentation of popular projects with packages on NuGet [...]

  8. Awesome effort you’re doing for docs, but wondering here why take such a *backward* (pardon the French) approach with NuDoq itself? Why not make NuDoq open source? Unless that’s an upcoming plan of action? Also, what’s with the “© 2013 Clarius Consulting” at the bottom? I mean, you don’t own the docs/content. :) Shouldn’t that read “NuDoq © 2013 Clarius Consulting”? If anything, the copyright notice & license from the NuGet package should be displayed with a separate one for community-contributed content. Again, awesome effort.