Comments on: Enhancements vs. Just Documenting It http://www.gryphonmountain.net/2008/08/enhancements-vs-just-documenting-it/ Technical Communication and Other Writing Topics (by Ben Minson) Thu, 11 Mar 2010 13:12:35 -0600 http://wordpress.org/?v=2.9.2 hourly 1 By: Ben http://www.gryphonmountain.net/2008/08/enhancements-vs-just-documenting-it/comment-page-1/#comment-14103 Ben Wed, 31 Dec 2008 23:40:48 +0000 http://www.gryphonmountain.net/?p=84#comment-14103 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." 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.”

]]> By: sameera http://www.gryphonmountain.net/2008/08/enhancements-vs-just-documenting-it/comment-page-1/#comment-14050 sameera Wed, 31 Dec 2008 11:27:37 +0000 http://www.gryphonmountain.net/?p=84#comment-14050 Or now that I think of it...... that for minor enhancements like this, documenting the change is also costly and maybe not necessary? Or now that I think of it……
that for minor enhancements like this, documenting the change is also costly and maybe not necessary?

]]> By: sameera http://www.gryphonmountain.net/2008/08/enhancements-vs-just-documenting-it/comment-page-1/#comment-14049 sameera Wed, 31 Dec 2008 11:26:32 +0000 http://www.gryphonmountain.net/?p=84#comment-14049 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! 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!

]]> By: Enhancements vs. Just Documenting It Writer River http://www.gryphonmountain.net/2008/08/enhancements-vs-just-documenting-it/comment-page-1/#comment-1864 Enhancements vs. Just Documenting It Writer River Tue, 12 Aug 2008 07:11:19 +0000 http://www.gryphonmountain.net/?p=84#comment-1864 [...] Gryphon Mountain Journals » Blog Archive » Enhancements vs. Just Documenting It. [...] [...] Gryphon Mountain Journals » Blog Archive » Enhancements vs. Just Documenting It. [...]

]]>