In addition to the complexity of gathering, organizing, and presenting technical information, technical writers have to deal with managing multiple versions of the same content. Sometimes the versions correspond to different versions of a product and sometimes they are tied to different products. For example we maintain documentation for at least two versions of four different products. Two of the products share content with a third product. Keeping track of what version of a document goes where and where to make changes so that they apply to the proper products and versions is complicated.
For the last ten years, I have worked at companies that use a source control system for documentation content management. In general, source control systems are a good match for a documentation content management system. They use a centralized repository for storing content objects. They provide change tracking and versioning. They provide mechanisms for managing and viewing different versions of the same set of content objects.
I personally have used ClearCase, Subversion, and Git. They all have done the job asked of them. In ClearCase we didn't really tax the system much. We were working with FrameMaker BLOBs and only working on a single version of the content at a time. We also relied on the build team to manage the view specs, the branching, the tagging, etc. We used Subversion in the same way we used ClearCase, but slowly started working with XML content objects that were shared across product lines. Things got trickier once we started sharing content and we lost the team that managed the views and the branching. By the time we got to Git, we were completely on our own managing a spaghetti of branches and tags.
The drawback to all of them is that they are tailored to being used by developers. The interfaces are hard to use and non-intuitive to writers. They also lack a lot features that writers need like searching content and flow control. For example, to get the proper view of a content library in SVN we had to write and maintain checkout scripts to get the proper versions of all the proper repositories. If you worked on multiple versions of a product, you needed to have multiple working copies. It works well when it is all set up properly, but it is a major pain point. It is also fragile. It is easy to make a mistake that breaks a lot of things and is hard to undo.
There has to be a better way. I had always heard that there were products that are tailored for managing documentation content, but never had budget.
Recently, I have started investigating CMS systems. The first trouble was figuring out what type of content management system. There are Web content management systems that are used to build Web sites. There are enterprise content management systems like Share Point that are designed to store all sorts of content objects.
I am interested in component content management systems. This type of system stores content modules that can be assembled into final documents. They typically use XML as the content model and provide features for dynamic ID generation and linking. They also typically offer hooks into the major XML editors. They also offer searching and process control features.
I don't expect that any system will completely hide the ugliness of managing multiple versions of a diverse set of content. It is an inherently tricky problem. There will always be the problem of maintaining a coherent methodology for identifying variants and making sure changes get applied to the proper variants, etc. My hope is that a CMS system places a more friendly veneer over the process so that it is easier for a writer to work with.
I'd rather have writers focused on content than on managing the versions of the content.
February 21, 2012
February 1, 2012
Difficult Things
For me the hardest writing task is rewriting old material. I'm not talking about updating something because the feature changed. I'm talking about reworking and reorganizing material that needs to be updated to fit into a new structure or that needs updating because it just needs to be better.
Writing new content is difficult. The cold stare of a blank space is unnerving. The research that needs to be done before writing even starts can be grueling. The reviews are sometimes long and require rerunning the gauntlet.
The challenge of staring down the blank page and getting to the end of the race is exhilarating. Learning the new information and filling up the page gives me an endorphin rush. The anticipation of the reviews makes the thrill of a good review huge and the challenge of addressing the review comments a savory challenge. The sense of accomplishment makes the pain worth it. Of course it also helps that writing new content does require quite as much groveling during resource planning meetings.
Reworking old content does require a good amount of groveling and doesn't have the same payouts. The endorphins don't rush; they trickle. The sense of accomplishment is hollow because all there is to show for the time spent is a shinier version of the stuff you already had.
Not only is the reward less, The rewriting is also just plain hard. Often times you need to relearn the feature or concept being discussed. You always have to make judgement calls about what information to cut or add. Then there is the angst of reworking another writers (you were another writer when you wrote the original content, time changes every craftsman) handiwork. The cold stare of a page full of words that you need to slay is unnerving and unforgiving.
If you do the rewrite well, then the suffering is worth it. You will have made a significant improvement to the quality of the documentation set. If you it OK, you may or may not have made an improvement. You just spent time spinning your wheels. Often times you will never get any feedback to know finite was well done or not. You will just have to decide on your own.
For me the answer is always that I could have done it better. Nothing is ever perfect and I'm always improving/growing/changing as a writer. I always look at the end result as good enough for now. Maybe that is why I don't write fiction or for magazines or newspapers. In those mediums you finish a piece and are done with it. In technical writing, at least in 21st century Web only technical writing, no piece of content is ever truly finished.
Writing new content is difficult. The cold stare of a blank space is unnerving. The research that needs to be done before writing even starts can be grueling. The reviews are sometimes long and require rerunning the gauntlet.
The challenge of staring down the blank page and getting to the end of the race is exhilarating. Learning the new information and filling up the page gives me an endorphin rush. The anticipation of the reviews makes the thrill of a good review huge and the challenge of addressing the review comments a savory challenge. The sense of accomplishment makes the pain worth it. Of course it also helps that writing new content does require quite as much groveling during resource planning meetings.
Reworking old content does require a good amount of groveling and doesn't have the same payouts. The endorphins don't rush; they trickle. The sense of accomplishment is hollow because all there is to show for the time spent is a shinier version of the stuff you already had.
Not only is the reward less, The rewriting is also just plain hard. Often times you need to relearn the feature or concept being discussed. You always have to make judgement calls about what information to cut or add. Then there is the angst of reworking another writers (you were another writer when you wrote the original content, time changes every craftsman) handiwork. The cold stare of a page full of words that you need to slay is unnerving and unforgiving.
If you do the rewrite well, then the suffering is worth it. You will have made a significant improvement to the quality of the documentation set. If you it OK, you may or may not have made an improvement. You just spent time spinning your wheels. Often times you will never get any feedback to know finite was well done or not. You will just have to decide on your own.
For me the answer is always that I could have done it better. Nothing is ever perfect and I'm always improving/growing/changing as a writer. I always look at the end result as good enough for now. Maybe that is why I don't write fiction or for magazines or newspapers. In those mediums you finish a piece and are done with it. In technical writing, at least in 21st century Web only technical writing, no piece of content is ever truly finished.
Subscribe to:
Posts (Atom)