In the age of agile, companies and teams all over are integrating new documentation practices as best they can in a more streamlined, cooperative practice environment. Continuous delivery of software or an integrated delivery environment can be a challenge not just for software engineers, but certainly for technical communicators. Hey, it’s hard to write the doc before the software has been written, quality-tested and everyone has had a chance to kick the tires and take the thing out for a drive. But we try. In a perfect agile world, there could be a new feature or function of software release once a day! But can we really write and revise documentation every day? That seems unlikely, and probably unnecessary. We know that our users don’t relish reading the documentation, after all.

It is a practical chorus in my office: “Who reads the doc?”

I argue often that those who read the doc are experiencing a pain point, and that it is my job to ease that pain before it becomes excruciating. They are undergoing the pain of introduction, installation, or – and we hope this is not the case – they’ve hit trouble.

So sometimes, it is indeed true that perhaps the doc should be updated daily, with new screenshots, demos, integrations…who knows? If something changes fast in the world of software, don’t we want the documentation to keep up as well? I definitely do.

There are some great tools in the field to help with automation of doc – At MadWorld, we got to see how Jenkins builds works with MadCap Flare to conduct an automatic publish (that is a dream of mine, believe me). I imagine the day when I can integrate development and documentation, but there are some days when that seems like a far-off dream. Should I be satisfied with just DITA? Of course not.

 

Having trouble picturing what I mean? Imagine this: I want to automate a document that provides the directions from my office to my home. I could write these directions, “Exit the parking lot by turning left onto Smith Street. At the stop sign, turn right onto Maple Avenue. Proceed one-point-three miles to Mary Street. Turn left onto Mary Street,” and so on until I reach my destination. I would have produced an accurate document reflecting the journey from office to home. However, on a sunny Tuesday, I discover that there is construction on Mary Street. The construction will last a week or more, so the directions to my house have changed – at least in the short term. I have to change the document, and I have to change it today. If I could dictate the directions to a VUI as I drive, I could have a new document in moments. In fact, as soon as I pass the construction and reconnect to a spot where the route is the same as the old document, I could stop the modification. I could merge the first document with the new one, republish, and my work would be complete.

That is just one way to automate, but since I am using a model of doc change while driving, I like it! There are of course other models of doc change while developing, but this one is pretty cool. I’m not sure there is a whole lot of need for updated turn-by-turn printed directions, but it was an easy model. Now imagine if I could apply this to updated installation for software, or a new release model for medication or pharmacopeia. I can go on and on about the potential, but if it is “dictate and publish,” it’s game on. If my developers can help talk through the model, I can clean up text with an editor and have my truly agile production line – shazam!

Text-to-speech modeling and agility are at the edge. Automating publishing is there, too. It will be fun to watch the merge points. (Merge, get it?) Get in the car, and let’s see where the construction zones are.