I’ve been looking at content at BMC and determining whether it belongs in a concept, reference, or task topic using DITA’s definition of a topic. I had one particular item that seemed like it could be arranged in several different ways with advantages and disadvantages for each method. I had a great conversation with a fellow writer and a technical editor in the car on the way back from our corporate offices in Houston, and I thought I’d capture that discussion in a blog entry. So here goes.
Background information for this task
Overall, the user wants to configure their shiny new BMC Performance Manager for Databases product. It’s a pretty flexible configuration process to accommodate the needs of different environments but also to balance out ease of installation and configuration. So, you can either have the product automatically configure everything (you have to have certain user permissions on certain objects to do so) or you can manually configure by editing some included scripts that will give the correct permissions to each individual object (also requiring certain permissions but gives you the exact knowledge of what’s happening to your database).
So, as you might have guessed, the manual configuration goal turns out to be the toughest to turn into topics. I decided to look at the tasks related to manual configuration and then write the supporting topics.
What’s the task here?
But is the task itself “manually configuring” or is it “editing scripts?” I finally decided the task itself is editing the scripts, much to my chagrin because it doesn’t sound like a goal-oriented task. In addition, the background information for knowing why you’d do auto vs. manual should be explained in a concept topic, I believe.
But here’s where the decisions got a little tougher. The supporting reference information is a table of the objects and the required permissions on each. Obviously exactly the sort of information the DBA needs to know to get the job done. However, the complication occurs when I see this big table listing the script names — is that a second reference topic supporting the task of editing scripts? It’s only two columns but it’s a matrix of three supported databases with at least three script names for each. It’s essential information, required in order to complete the task of editing a script for manual configuration.
Do you put reference info in with the task if it’s critical for completing the task?
So do I keep that reference information with the task itself to avoid separating it into a standalone topic? Or assume the reader might come to that topic from many different directions so it should be by itself but in a related links link from the task.
Final decision – make it a topic
In the end, I decided that for ease of reuse and to offer multiple entry points to the information, I would make the script table standalone as a separate topic. It seems like the benefits are that the user can find that topic more easily and also that reference info can be related to other tasks as well. Other deliverables may also want to include that reference information so designing for re-use seems like a benefit here as well.
I’m still a little uneasy about my final decision to make four topics out of what is essentially one end-user goal — to manually configure their product. Does anyone who does topic authoring often have any suggestions?
Parting thoughts on the complexity of software documentation
This type of configuration complexity is why many examples in topic authoring presentations and articles ring hollow to me. Examples of the portability of telephone pole repair manuals and the task-orientation of cell phone manuals are not the types of concrete questions I ask myself every day when writing software doc. The classic example of “Hold the power button for 0.7 seconds” as a poor example of a step in a task immediately comes to mind. An equivalent software documentation example is much more complex than instructions for a task on a cell phone.
Software doc lives in the abstract. Instead of an easily known or recognizable metaphor, I’m faced with products that are increasingly flexible but that flexibility causes the user to be faced with many micro-decisions. I think it’s my responsibility to guide the user through their choices and offer the technical advice for them to make the best decision, no matter how they’ve approached the doc in the first place. (from a search engine? from the table of contents?) It isn’t easy but oddly enough I enjoy the hunt for the best content organization and chunking possible.