Automating Documentation
One of the things that I've been doing lately is writing reference documentation for my projects. Squidhead has an extensive set of configuration options, and an internal project has a custom XML format. I thought I would share the method I've come up with to make it much easier for me to do.
The problem with this type of documentation is that is really easy to do once and then not keep up to date. When coming up with a solution, it had to be repeatable and additive. You could just read in all that information and recreate dynamically from scratch, but that means you can't manually alter the documentation. I was looking for something that would basically just remind/force me to document new options or files. With that in mind here is what I do:
- Assume that I am documenting a set of configuration files
- Create an XML file where each file to be documented is a node
- Do a directory list of the files to be documented
- Grab the name of each file
- Check to see if a node currently exists in the XML for each file.
- If not I add a node named after the file
- Create blank sub nodes for "documentation," "notes," or "required" or whatever
When that pass is done:
- I scan the XML
- I check for blank sub nodes.
- If any exit I throw an error
I then add this process to my ANT build for the project. Now every time I go to build the project, the documentation gets scanned, added to if needed, and I am prevented from moving forward until I document new changes.
This turned documentation for me from an incomplete mess of a task that takes two hours or so every few weeks to 5 minute maintenance step every time I build.
4 responses so far ↓
1 Hal Helms
Nice idea, Terrence. Documentation is too often left for last (or not at all). As you said, the key is having something that's easy and automatic.2 Terrence Ryan
Thanks, Hal, that is high praise coming from you.3 Jim Priest
Can we see some code :)This sounds really cool and anything integrated with Ant is a plus! :)
4 Terrence Ryan
I'll try and post something this weekend.Leave a Comment