Writing documentation

While the act of writing documentation is usually pretty boring it feels good when it comes together. At least it gives you a short-lived feeling of accomplishment. That is until you realize that nobody cares enough to read your documentation.

If you have to write a lot of technical documentation for code I would recommend you cling to DRY (Don’t repeat yourself). The system that Brent and I worked on is pretty nice you take XML comment autodoc, tranform it with XSLT and get pretty documentation to impress your managers. You embed the XML comments in your code and you can single source everything. The XSLT auto-generates table of contents and other standardized formatting trinkets.

The only thing that is still annoying me about this system is that I embedded XHTML to get accurate table output in the comments. I really should have schematized this but I was too lazy. Well for the time being it is Good Enough.