So, I’ve gotten into documentation lately, which feels a little weird for me. I don’t think of myself as a documentation person, but instead as one of those people that should write it but never does. I’ve noticed myself drifting this way over the past few years, and I guess it isn’t a bad thing. :-)
So, I attacked the install guide a few months ago, and ever since I’ve been itching to do something about an administrator’s guide and a reference guide. I just got back from a week-long vacation, and I had planned to do some hacking on OpenNMS while I was away. Well, most of what I got done was hacking not on code, but on documentation–this time for our XML schemas. These define what is allowed in OpenNMS’s XML configuration files, and probably more importantly from a developer’s standpoint, they used as input to Castor to automatically generate Java code that we then use to access the XML files.
It turns out that XML schemas allow embedded documentation pretty much anywhere in the schema inside of almost any element. There are a few tools out there to take this documentation embedded in the schemas and make a user-friendly representation of it, and I chose the open-source xsddoc tool (part of the xframe project) do do the work for us. The only thing left for me was add the
I committed my work last week into HEAD (the “unstable” branch), and I also have a copy of it on my website. There are some bugs in xsddoc that need to be worked out, and it could use some enhancements, but so far, I’m pretty happy with it. It was definitely a lot easier than writing everything by hand, and is a lot more maintainable.
That’s all for now, folks!