The Doc Tools Conundrum

Started reading the Designer's Guide for MT4. As you might expect, Movable Type itself is used to maintain and host the content. People documenting Web CMSs always do this: use the product itself for the product docs. I suppose it's a natural thing to do, but it can be frustrating for the reader if the CMS isn't good at structuring content -- and Movable Type is not. There's only rudimentary breadcrumbing, and no automatic generation of "next" and "previous" links.

One of the challenges I've been facing as a tech writer is the growing preference for this kind of quick-and-dirty approach to documentation. I saw a lot of it at Sun, and the impression I got then was that it was part of the current infatuation with wikis and other crowdsourcing technologies. But I'm beginning it see that it also has a lot to do with the rise of Agile software engineering. If the software development cycle can be streamlined, deformalized, and drastically shortened, why can't you do the same with the documentation cycle?

Well, there are reasons, but I'm not going to get into it now. Suffice to say that I believe that documentation needs to be more structured, not less.  However, this is not an issue you can deal with through argument; the issues are just not understandable to most engineers. (Or a lot of tech writers, for that matter.) You have to demonstrate how structured methods make for better docs. And you have to do it in such a way that your formalized doc process fits in with the deformalized software development process.

It's a pretty problem. I suspect the answer might involve using both formal (XML, specialized authoring software, etc.) and informal content management tools. More on that later.

Zemanta has suggested a lot of related articles, based on what I just wrote. I'm going to insert links to some of the more interesting ones, without too much regard to their being ontopic.

Related articles by Zemanta

• Does Agile Development Matter? (devx.com)
• Agile Across the Enterprise: Prioritizing Value in Support and Training (tc.eserver.org)
• Blog Software Update (onemanandhisblog.com)
• Agile Software Development With Scrum (slideshare.net)
• Top Most Usable Open Source Content Management System- CMS Software for your organization (ceoworld.biz)
• TPM on Rails: Building a News App in Under Two Months (shhhaw.com)