Enhancements vs. Just Documenting It
August 11th, 2008I’m back in the saddle after camping and then participating in a pioneer handcart trek reenactment last week. The world at work moved on without me, but not far enough that I wasn’t able to get back into things quickly.
A program manager and I were helping some users today when he talked about getting their feedback on aspects of the design that don’t work for them; for example, we have a page in the application with a lot of text boxes, and in order to save page scrolling, these text areas were designed to be three lines high. Therefore, if there are more than three lines of text in a box, scrolling that box becomes necessary. The users were accustomed to seeing all the text at once on paper, so they wanted the same thing on the screen.
The program manager told them that their feedback would be taken into consideration for enhancements in future releases. This made me ask myself when it’s better to enhance the product or simply explain the current state in the documentation. Where’s the line?
A coworker who used to be a technical writer once gave me a pin he received at a conference. The pin reads: “NO. You can’t just explain it in the manual.”
The point is that documentation shouldn’t have to make up for lack of design. However, there are probably some cases where adding some information to the documentation instead of changing the product makes more sense. Cost of doing one or the other is certainly an important consideration. The degree to which the enhancement would relieve user headaches is another.
Where only one of the two is needed, how do you make the determination whether to enhance the product in a certain way or instead add to the documentation?
Subscribe to the Journals
August 12th, 2008 at 1:11 am
[...] Gryphon Mountain Journals » Blog Archive » Enhancements vs. Just Documenting It. [...]
December 31st, 2008 at 5:26 am
Hi Ben,
Sorry that this is coming up this late after your post, but could you explain more in terms of the example you state?
Are you trying to say that in the case above, you would explain to the users that scrolling is needed once the number of lines exceed three? And probably the cost of documenting this is better than having to change the product?
Thanks!
December 31st, 2008 at 5:27 am
Or now that I think of it……
that for minor enhancements like this, documenting the change is also costly and maybe not necessary?
December 31st, 2008 at 5:40 pm
In this particular example, I might not document the enhancement because it’s what the users expected to see in the first place. It also wouldn’t make sense to say “You can see all the text with no scrolling” (duh…?) The original issue seems to need some mention because the users noticed that they weren’t seeing all the text if it exceeded three lines. Perhaps the fact that scrolling is needed for more than three lines in itself doesn’t need documentation. Here’s some complexity for you. One role that can view the page can’t edit the text boxes, so they’re grayed out. Therefore, if the text exceeds three lines, they can’t scroll to read the entire contents. However, the page was coded so that if they print it, all the text shows up. (And this is for a system that is supposed to save paper in a previously paper-heavy process.) So that was the bigger problem and turned out to need some documentation at least for the interim.In thinking about this post, I don’t know if I would do much to change the documentation for the specific issue I mentioned. I think my point was just that our interaction with the users prompted me to think about enhancements vs. just explaining the way the product is and which is more costly. I think the technical communicator simply adding a sentence or two to the documentation is cheaper than changing and testing code, which probably leads to the developer’s request to “just explain it in the manual.”