Proactive and reactive

Writing the previous post it occurred to me that I work in two modes most of the time:

• First, I work with architects and developers, helping a feature get designed for usability, and writing as we go. My work as part of that team is part of the feature development. This is the proactive mode.
  
• Later, I step back to view the product as a whole, and reactively describe the feature in that context. Developers can deliver a feature, say, "that's enough", and move on to the next one. I don't have that luxury; people will experience the feature as part of the complete system, and they need to know how to find it and work with it in the context of everything else the system is doing.

The "structured" / "traditional" authoring debate is a struggle between these two modes. Each style pulls in the favour of one mode, although we always need both.

• Structured authoring, as exemplified by DITA, is a proactive mindset. Topics should stand alone and tell people exactly what they need right now. They are authored separately from each other, and pulling a document together is deferred until the last possible moment (and may never happen, in the case of a knowledge base.)
  
• Traditional authoring is a reactive mindset. The product is delivered fully-formed and is documented as a unit. In the OpenOffice authoring project authors work on entire chapters, which are organized according to user needs. Despite being an important part of a huge, global open source project, it's entirely divorced from the collaborative, proactive mode which is natural for the developers of the actual product.
  

Personally, I like being able to work with developers, and to promote design choices which improve usability, and the reuse abilities of structured authoring allow me to maintain, on my own, a much larger information base than I would be able to if I had to manage documents individually.

But it's in the reactive mode that information gets consolidated and where, in the end, the user's experience of the product is decided for better or for worse.

Source control

A big advantage of using structured authoring for me is the ability to use our existing source control system for documentation.

Source control is all about people working simultaneously on a large set of files. An SCM tool is a collaboration tool, not a software development tool. Sure, it's quite a technical one, but SCM tools have evolved to deal with enormous codebases, and thousands of developers working on the same product.

As a software company, our developers work in source control all the time. A team goes off and develops a feature, and comes back, and merges the feature back into the product. That merge process is largely automatic, and once it's done, the feature gets incorporated into the product with no fuss.

I can do exactly the same for the documentation. I don't even have to be present when the feature lands: a lot of the time, the only file that conflicts is the map file, and the SCM system is smart enough to figure it out for itself.

Even if I wasn't at a software company, this idea that you can develop new features separately and easily combine them later is useful enough that I'd probably want to maintain a SCM system of my own to do it with.





* Actually, it doesn't even ask this most of the time, but if you have one file for each topic, it makes merging easier.