Some words about a project idea codenamed Duchess - the goal is to make a replacement for Sandcastle and make creating documentation for open source project cool again

duchess.md

Burn Sandcastle to the Ground

Addressing The Documentation Problem

I've had lots of discussions with people over the past few days around how open source projects in the .NET space have poor documentation (if it exists). So how do we fix this?

At a high-level, I've got these goals in mind:

• make it easy
• make it cool
• leverage existing work in the .NET space
• bring in cool ideas from other ecosystems

I am going to codename this thing Duchess in lieu of a better name.

Make It Easy

One of the big reasons why Sandcastle has such a bad name is because it is really hard to setup (and automate).

Duchess should be one thing that can be run from the command line.

Duchess should be NuGet-able.

Duchess should be opinionated enough that you just point it at your project folder and it should just work. Opinions like:

• docs folder representing the site template
• Markdown for custom docs
• scan for //bin//*.xml (warning: probably not a real wildcard) files and use those for your APIs
• use magical unicorns to weave together custom Markdown files with generated documentation

Make It Cool

CHM files are a relic of a bygone era. Just let them go.

Duchess should generate a site or something that people actually like.

The default site should contain things like Bootstrap so that the site looks pretty out-of-the-box.

It should work with GitHub pages, or allow people to just deploy it like a static site.

Jekyll is a popular-enough static site generator that I'll generally defer to their conventions.

Leverage Existing Work

Developers still like using XML documentation.

We should parse that as a starting point, and that would require the output to behave something like CHM to help migrate existing projects across (unless they want to break their Google juice).

Cool ideas

• runnable code snippets (using LinqPad) which will fail the site generation if they don't work
• git push should let developers publish the site to Azure/Heroku (oh dear what am I thinking)
• annotate your source code -> documentation picks it up

What's next?

• spike something that'll take an XML documentation file and generate Markdown
• a simple site template using Bootstrap but with treeview-like behaviour (ew, maybe something better)
• people to contribute their thoughts on this

ETA: no clue. I'm exhausted and going on holidays in a few days.

Feel free to leave a comment or ping me on Twitter - I'm @shiftkey.

Random ideas from a brainstorming session over dinner this evening:

• extend the VS IDE to allow users to annotate the class/method (which are stored in a different location to the code) as a simpler version of XML documentation
• some developers open a browser to the documentation site - it would be cool to do this inside a different VS panel. For additional awesome the browser could navigate to the current API you're focused on automagically (could be annoying)

Moving this discussion to here so I can write proper specs and allow others to contribute directly.