It takes a lot of time writing it and writing decent documentation it is an art in itself. Writing good documentation is a full-time gift.
Doc it like it’s 1999
I decided very early on boarding OSS that I would commit the time to write API documentation, regardless of my 3 tenets:
- First directive is API design
- Second directive is API design
- When directives One and Two fail, documentation prevents total failure
Not only NMoneys comes with full-fledged XML documentation, some builds ago I included a .chm for old times’ sake.
But Mum does not (usually) feed me anymore
I even thought of a plan to not only compile the API documentation into .chm, but take advantage of the html generated and push it somewhere online.
And then, she passed by. Casually. Without giving herself importance. And I laid my eyes on her. Nudoq, from now on you have female gender in my vocabulary
I read about it while reviewing the project site of a random OSS library and it totally blew me off my socks. That is exactly what I had been looking for: good-looking, online documentation that takes no effort beyond documenting your code.
It works without you noticing. As long as you include XML comments in your code and push it to Nuget, chances are that she made your documentation available to everyone already.
She did that to NMoneys, check it out if you don’t believe your eyes.
All that glitters ain’t code
Unfortunately, it is not perfect.
I found myself some issues: failing to document inner classes, weird rendering and failing to refresh the documentation whenever a new version (or three) are pushed to the Nuget Gallery.
Something that worries me a bit, is that even though there is a Github organization for it, I cannot find a repository to clone and contribute to. There is a post in their feedback forums stating that it may be on its way, but it is from some time ago and it has not received much attention.
It would be a pity that it was not open sourced, since I am more than willing to contribute to such an awesome idea.
Please, let me work for you for free.