http://www.gryphonmountain.net/2008/11/usability-vs-maintainability-in-technical-documentation/ Technical Communication and Other Writing Topics, by Ben Minson Wed, 11 Jan 2012 04:05:49 +0000 hourly 1 http://wordpress.org/?v=3.0.4 http://www.gryphonmountain.net/2008/11/usability-vs-maintainability-in-technical-documentation/#comment-200 Kristi Mon, 24 Nov 2008 16:48:39 +0000 http://www.gryphonmountain.net/?p=187#comment-200 I've been thinking about this, too, because I'm working on a project that was recently imported into Flare to be single-sourced. On top of that, the product is now in rapid development instead of waterfall development. So the whole project has leaped into the 21st century. Warts and all; inconsistent headings and organization, incompletely documented features, etc. So, another writer and I are trying to clean those things up while adding a long list of changes on an aggressive schedule. Prioritizing is a must. I have been reassuring myself with every change I document, “You got the main flow of the change. You tried to find every procedure and window that may be touched by this change,” (I’m new to the product, too), “but it’s possible you missed a minor one. Users will be able to find the topics you wrote and get the information they need. Time is up for this change.” In the example of the button that you gave, if the button moves or changes, you’ve got rewrites in every procedure it is listed in. If you have it in a snippet or variable, you have to rewrite each snippet or variable for each button that moved. If you’re in my shoes, you have to find every place the step occurs and turn it into a snippet or variable. It may be that time could be better spent documenting a change that is more likely to stump people. If there is no procedure on how to web-schedule a patient, for example, maybe more people will have trouble than if you omit a detailed description of where to find the Power button. That said, I do like to have an image of a button; especially if the button contains no text. I’ve been thinking about this, too, because I’m working on a project that was recently imported into Flare to be single-sourced. On top of that, the product is now in rapid development instead of waterfall development. So the whole project has leaped into the 21st century. Warts and all; inconsistent headings and organization, incompletely documented features, etc. So, another writer and I are trying to clean those things up while adding a long list of changes on an aggressive schedule. Prioritizing is a must. I have been reassuring myself with every change I document, “You got the main flow of the change. You tried to find every procedure and window that may be touched by this change,” (I’m new to the product, too), “but it’s possible you missed a minor one. Users will be able to find the topics you wrote and get the information they need. Time is up for this change.”
In the example of the button that you gave, if the button moves or changes, you’ve got rewrites in every procedure it is listed in. If you have it in a snippet or variable, you have to rewrite each snippet or variable for each button that moved. If you’re in my shoes, you have to find every place the step occurs and turn it into a snippet or variable. It may be that time could be better spent documenting a change that is more likely to stump people. If there is no procedure on how to web-schedule a patient, for example, maybe more people will have trouble than if you omit a detailed description of where to find the Power button.
That said, I do like to have an image of a button; especially if the button contains no text.

]]>