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.
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
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.
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).
- 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
- 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.
The JavaScript community have had some good improvements in this space in recent months (years?) that would be a good place to take ideas from. Two projects which come to mind are JSDoc and Docco.
These are both static site generators (well JSDoc uses 3rd party tools like JSDoc Toolkit to do that) which use JavaScript-friendly versions of XML comments.
Docco is a bit more advanced as it allows you to do comments anywhere in your source that you generate your documentation site from. Docco is just a command-line tool that you can easily plug into a build system so that's a good example of how to do the workflow you're talking about.