Comments on: Reveal Bugs in Release Notes, Not User Guides http://www.gryphonmountain.net/2009/06/reveal-bugs-in-release-notes-not-user-guides/ 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 By: xJAYMANx http://www.gryphonmountain.net/2009/06/reveal-bugs-in-release-notes-not-user-guides/#comment-317 xJAYMANx Wed, 24 Jun 2009 06:17:41 +0000 http://www.gryphonmountain.net/?p=622#comment-317 @Ben: Yup, I agree. Leave the bugs out of the user docs. Not because we're writing "fiction" or "truth", but because first of all, it assumes that the bugs occur in all environments for all users. Which may not be the case. So why point them out to users who may never encounter them? Secondly, noting bugs would tend to disrupt the "flow" of the content or user experience. I'm not a foreign-language translator or interpreter, but let's put it this way: Does an English interpreter repeat every pause, cough, hiccup and stutter of the original Japanese speaker? Or would she or he "smooth" out the flow of the translation? I would tend to believe the latter. The same goes for user guides. ^_^ @Ben: Yup, I agree. Leave the bugs out of the user docs. Not because we’re writing “fiction” or “truth”, but because first of all, it assumes that the bugs occur in all environments for all users. Which may not be the case. So why point them out to users who may never encounter them?

Secondly, noting bugs would tend to disrupt the “flow” of the content or user experience. I’m not a foreign-language translator or interpreter, but let’s put it this way: Does an English interpreter repeat every pause, cough, hiccup and stutter of the original Japanese speaker? Or would she or he “smooth” out the flow of the translation? I would tend to believe the latter. The same goes for user guides. ^_^

]]>