Five areas of documentation that need continuous monitoring
When I first started working on DevOps-related software, continuous monitoring didn't sound like something that was big enough to be one of the pillars of a new software methodology. My dev-centric background was part of why I discounted monitoring, but I also figured that if we were already automating things like deployment and testing, wouldn't the tools already record things like test results? Big deal! The most popular thing I've yet written is a seri
Then, early in my DevOps work, I had a long talk with Bill Higgins (@BillHiggins), who at the time was one of the architects in charge of those projects. Bill's simple and direct example was performance testing: if we did a lone performance test at the end of a release and that test showed that a certain process takes two minutes to run, how can we tell if that's a good time or not? We don't have any other reference points. If we run that performance test regularly, we can see exactly when the process time jumps from 30 seconds to two minutes. That information helps us find the change that caused that slowdown. For more info on continuous monitoring, here's an introduction by Sanjeev Sharma: “Und
So I'm a continuous monitoring believer now, and I'm looking for ways that better monitoring can help in my work documenting software with IBM Rational User Technologies (@RationalUT). Here are some places that have come to mind:
Within IBM Rational, we use IBM Rational Policy Tester as part of our accessibility testing and compliance certification. We're early in the adoption process, but at this point we use the tool to check for accessibility issues, from simple things like missing alt text to more complicated things like navigation problems that can confuse screen readers and other accessibility tools. If we ran this kind of test automatically, it would be easier to fix these problems because we'd find out about them immediately after we've committed a change, rather than during a full-product accessibility scan months later.
Translation word counts
I've already written about this in a little more detail, but in short, we can use continuous monitoring to keep a close eye on the delta between documentation that has already been translated and what we're writing now. The resulting information makes it easier for us to plan translation drops and for translators to know how much work is coming down the pipe.
I'm not sure how wide this kind of practice is throughout the tech writing discipline, but in IBM Rational, we use the Acrolinx IQ automated tool to check files for stylistic and legal issues. Like most writers, I bristled at having a computer check my writing, but over time, it became a natural part of my process.
Currently I'm working on bringing in the documentation from the UrbanCode acquisition and getting it up to IBM style guidelines. For uDeploy (now IBM
Trademarking and legal check
We've got an internal tool that stamps trademarked terms with the proper symbols and checks to make sure that we're using these terms correctly. However, the process isn't completely automatic yet—it needs to be part of our regular build process. After looking at all of the things that our development and operations team can automate, I'm surprised that we still have to remember to do this manually.
Here's an area that we're getting good at. We keep track of how many hits each documentation page gets and what people are searching for. Over time, we've become more interested in which pages are not being visited than which pages are popular. If an area of the documentation (or even a single topic here and there) isn't being visited, that area is either not done well or not worth our limited time to work on. If people are searching on certain terms and aren't finding anything, we need to rethink our terminology. We can also track how these statistics change as we update and change the documentation, and we're only getting started mining this data.
I'm sure that there are other areas of the documentation process that would benefit from continuous monitoring and other DevOps principles. I'll keep posting here, and you can let me know if you've got thoughts here or on Twitter: @timothymcmackin.