Treat documents like software

This is a followup to my earlier article about Agile and documentation projects.

I’m currently working on a document in which I’m outlining a group of processes within our application. My manager sent me a JIRA ticket to track the project. The ticket includes a few sub-tickets to track some of the specifics of the project.

It then occurred to me how we’re able to make documentation projects work in an Agile environment. It’s something I’ve been espousing for a while; in fact, I even make mention of it in my documentation presentation. I even made mention of it when I presented it a couple of weeks ago. (Ed. note: I wish I’d thought of this when the gentleman asked me this question at that user group meeting!) As it turns out, the answer is pretty simple.

The answer: treat documents like software.

Too often, documentation is treated like a second-class citizen. It gets absolutely no respect. That lack of respect is why I travel to SQL Saturdays preaching the gospel of documentation. Documentation is an important piece when it comes to technology planning; yet it is often treated as an afterthought.

In my current working environment, what makes document projects work in Agile is that they are treated with the same level of importance and respect as application updates. In a sense, document updates are application updates. They are important for end-users and developers alike.

In my daily Scrum meetings, I discuss progress made on my projects — almost entirely documentation projects. These projects are discussed on the same level as application and database updates. Tickets are created and tracked for these projects — just like applications.

I’ve had the luxury of having worked in both professional software development and technical writing environments. I can tell you from firsthand experience that the development lifecycle between the two environments is no different. So why do technical managers keep insisting on treating documentation differently? We are able to make documentation work because it is treated on the same level of importance and respect as application updates. Granted, it might be handled with a lower priority level (that’s okay), but the way documentation is handled is no different from the application.

If you want your documentation to be successful, consider it at the same level as you would your software development. It is a critical part of technology development, and it needs to be considered with the same level of respect.

Can Agile and documentation projects co-exist?

When I spoke at the New England SQL user group meeting yesterday, an interesting question came up. An audience member spoke about Agile development, and he mentioned that, because of the nature of Agile, document projects were doomed to fail.

At this point, I should mention a few things.

  1. I currently work in an environment that uses Agile development methodology.
  2. Just because I work in said environment doesn’t mean I know anything about Agile.
  3. Even as my workgroup’s technical writer, I am considered a highly valued member of the workgroup.
  4. Somehow, we make it work.

In regards to #4 above, the gentleman had a simple question: “How?”

This question came up during a point in my presentation in which I argued that document projects should be treated like software — in that, in an ideal environment (stop snickering!), a formal document should be subject to planning, development, and testing. This is a point that I’ve alluded to before.

The person asking the question went as far as to say, “if you can make the case as to how Agile can make technical writing projects work, then you should make a presentation out of it — and I’ll even help you sell it to Agile.” He even gave me his business card. Indeed, one of my big reasons for writing this article is as a reminder to myself to revisit this subject — after I’ve had a chance to do some homework about Agile development. It’s something I’ve been meaning to do; I even went as far as to begin a draft article about Agile development.

So, to the gentleman who brought up this (great) question, you were heard. And I will make sure that I come back to this at some point — once I’ve had a chance to do my homework on Agile.