Comments on: The Myth of Simplicity and Complexity in Help Authoring http://idratherbewriting.com/2008/08/01/the-myth-of-simplicity-and-complexity-in-help-authoring/ The Latest Trends in Technical Communication Sat, 26 May 2012 05:09:12 +0000 hourly 1 http://wordpress.org/?v=3.3.2 By: The Naked Tech Writer « ffeathers — a technical writer’s blog http://idratherbewriting.com/2008/08/01/the-myth-of-simplicity-and-complexity-in-help-authoring/comment-page-1/#comment-137147 The Naked Tech Writer « ffeathers — a technical writer’s blog Mon, 26 Jan 2009 05:17:23 +0000 http://www.idratherbewriting.com/?p=1764#comment-137147 [...] Tom Johnson has the topic of simplicity well covered. (Please excuse the number of awful puns that I suspect will appear in this blog post. They’re irresistible.) So I thought I’d look into the other possible interpretations of our new nickname, The Naked Tech Writer. [...] [...] Tom Johnson has the topic of simplicity well covered. (Please excuse the number of awful puns that I suspect will appear in this blog post. They’re irresistible.) So I thought I’d look into the other possible interpretations of our new nickname, The Naked Tech Writer. [...]

]]> By: Jordan Frank http://idratherbewriting.com/2008/08/01/the-myth-of-simplicity-and-complexity-in-help-authoring/comment-page-1/#comment-133761 Jordan Frank Tue, 19 Aug 2008 18:26:11 +0000 http://www.idratherbewriting.com/?p=1764#comment-133761 Help authoring in a wiki is ideal since the page format lends itself to chunking help tips into small pages rather than chapters. Using categories can also be a big improvement as well, to add a dimension to any written TOC or index. It can also help distribute the authoring process. The most difficult hurdle I've faced is the need to focus on "how do I use a given tool?" vs. "how do I apply the tool to a given use case?" In the former case, you are answering "what exactly does each button do" and in the latter case you are answering "why would I use that button?" or "how would I use that configuration option to solve a particular problem?" The latter is difficult as the answer generally depends entirely on the organization and need for which the software is deployed. When the two types of answers start to intermingle, it adds the sort of complexity that may turn some people off. Help authoring in a wiki is ideal since the page format lends itself to chunking help tips into small pages rather than chapters. Using categories can also be a big improvement as well, to add a dimension to any written TOC or index. It can also help distribute the authoring process.

The most difficult hurdle I’ve faced is the need to focus on “how do I use a given tool?” vs. “how do I apply the tool to a given use case?”

In the former case, you are answering “what exactly does each button do” and in the latter case you are answering “why would I use that button?” or “how would I use that configuration option to solve a particular problem?”

The latter is difficult as the answer generally depends entirely on the organization and need for which the software is deployed. When the two types of answers start to intermingle, it adds the sort of complexity that may turn some people off.

]]> By: Robert Nagle http://idratherbewriting.com/2008/08/01/the-myth-of-simplicity-and-complexity-in-help-authoring/comment-page-1/#comment-133479 Robert Nagle Fri, 08 Aug 2008 17:50:29 +0000 http://www.idratherbewriting.com/?p=1764#comment-133479 I'm a technical writer who was one of the early adopters for Wordpress in 2003. I don't disagree with your main points, but I've been pleasantly surprised at how manageable the wp docs have become with the codex. It looks nice and manages to answer most of my questions. I like how they've integrated the forums with third party products. I also like the way anchors generate a built-in TOC of hyperlinks for the same page. Also, I think the UI for wordpress is one of the easiest I've encountered (which reduces the need for clear documentation). The WP people have assumed (correctly I think) that a usable GUI reduces the need to document for newbies. Anyway, if people need help performing basic functions, they need a screencast, not a written document. I think what people need is a TOC page with a list of common tasks, from easiest to hardest. Also, it should be easy for wordpress to have hooks at various points in the interface to user-oriented documents in the codex. Also, they need to separate conceptual issues from practical issues. They are mixed in together, and sometimes it's hard to find the doc you really need. Also, more than having a technical writer they need someone just to delete or prune all the pages with outdated information! Finally, the real pain points are not in wordpress but in theme management, change management and third party plugins. Those things are where I spend 95% of my time trying to troubleshoot. By the way, the drupal documentation is a lot more chaotic than wordpress. Robert Nagles last blog post..<a href="http://www.imaginaryplanet.net/weblogs/idiotprogrammer/?p=83399896">Back to Houston, Back to Work</a> I’m a technical writer who was one of the early adopters for WordPress in 2003. I don’t disagree with your main points, but I’ve been pleasantly surprised at how manageable the wp docs have become with the codex. It looks nice and manages to answer most of my questions. I like how they’ve integrated the forums with third party products. I also like the way anchors generate a built-in TOC of hyperlinks for the same page. Also, I think the UI for wordpress is one of the easiest I’ve encountered (which reduces the need for clear documentation). The WP people have assumed (correctly I think) that a usable GUI reduces the need to document for newbies. Anyway, if people need help performing basic functions, they need a screencast, not a written document.

I think what people need is a TOC page with a list of common tasks, from easiest to hardest. Also, it should be easy for wordpress to have hooks at various points in the interface to user-oriented documents in the codex.
Also, they need to separate conceptual issues from practical issues. They are mixed in together, and sometimes it’s hard to find the doc you really need. Also, more than having a technical writer they need someone just to delete or prune all the pages with outdated information!

Finally, the real pain points are not in wordpress but in theme management, change management and third party plugins. Those things are where I spend 95% of my time trying to troubleshoot.

By the way, the drupal documentation is a lot more chaotic than wordpress.

Robert Nagles last blog post..Back to Houston, Back to Work

]]> By: Tom http://idratherbewriting.com/2008/08/01/the-myth-of-simplicity-and-complexity-in-help-authoring/comment-page-1/#comment-133376 Tom Tue, 05 Aug 2008 05:02:17 +0000 http://www.idratherbewriting.com/?p=1764#comment-133376 @Lulu, I listened to a podcast with the author. If you go to wordpresspodcast.org, and search for the book title, you'll find the podcast. It seems pretty basic, and I don't know who they can keep it updates with releases every quarter. Still, it may be just the thing you need to get started. @Lulu, I listened to a podcast with the author. If you go to wordpresspodcast.org, and search for the book title, you’ll find the podcast. It seems pretty basic, and I don’t know who they can keep it updates with releases every quarter. Still, it may be just the thing you need to get started.

]]> By: Lulu http://idratherbewriting.com/2008/08/01/the-myth-of-simplicity-and-complexity-in-help-authoring/comment-page-1/#comment-133346 Lulu Mon, 04 Aug 2008 14:46:55 +0000 http://www.idratherbewriting.com/?p=1764#comment-133346 Well...there is a WordPress for Dummies, but I haven't bought it yet, although I am seriously considering it... http://www.amazon.com/dp/0470149469?tag=leawilartbyna-20&camp=14573&creative=327641&linkCode=as1&creativeASIN=0470149469&adid=1R29V58YM2VB7264C27Z& Well…there is a WordPress for Dummies, but I haven’t bought it yet, although I am seriously considering it…

http://www.amazon.com/dp/0470149469?tag=leawilartbyna-20&camp=14573&creative=327641&linkCode=as1&creativeASIN=0470149469&adid=1R29V58YM2VB7264C27Z&amp;

]]> By: Reader Question — How Do I Get Training in Technical Writing? | I'd Rather Be Writing - Tom Johnson http://idratherbewriting.com/2008/08/01/the-myth-of-simplicity-and-complexity-in-help-authoring/comment-page-1/#comment-133324 Reader Question — How Do I Get Training in Technical Writing? | I'd Rather Be Writing - Tom Johnson Mon, 04 Aug 2008 05:47:03 +0000 http://www.idratherbewriting.com/?p=1764#comment-133324 [...] the steps. Include screenshots where the steps are confusing. Chunk the material into tasks. See my post on the complexity of simplicity for some standard [...] [...] the steps. Include screenshots where the steps are confusing. Chunk the material into tasks. See my post on the complexity of simplicity for some standard [...]

]]> By: 511 pants http://idratherbewriting.com/2008/08/01/the-myth-of-simplicity-and-complexity-in-help-authoring/comment-page-1/#comment-133286 511 pants Sat, 02 Aug 2008 12:31:40 +0000 http://www.idratherbewriting.com/?p=1764#comment-133286 Thanks for the useful information Thanks for the useful information

]]> By: » The Myth of Simplicity and Complexity in Help Authoring | I’d Rather Be Writing - Tom Johnson Writer River http://idratherbewriting.com/2008/08/01/the-myth-of-simplicity-and-complexity-in-help-authoring/comment-page-1/#comment-133280 » The Myth of Simplicity and Complexity in Help Authoring | I’d Rather Be Writing - Tom Johnson Writer River Sat, 02 Aug 2008 05:43:26 +0000 http://www.idratherbewriting.com/?p=1764#comment-133280 [...] The Myth of Simplicity and Complexity in Help Authoring | I’d Rather Be Writing - Tom Johnson.   [...] [...] The Myth of Simplicity and Complexity in Help Authoring | I’d Rather Be Writing – Tom Johnson.   [...]

]]> By: Craig http://idratherbewriting.com/2008/08/01/the-myth-of-simplicity-and-complexity-in-help-authoring/comment-page-1/#comment-133259 Craig Fri, 01 Aug 2008 14:38:01 +0000 http://www.idratherbewriting.com/?p=1764#comment-133259 when I went to WordPress to start my blog, I was overwhelmed. Having a 'Before You Install' to read is bad. I just wanted to get started. When I began reading it, I fogged over. I asked My Better Half about it. She didn't even bother looking up. She told me to go to Blogger. I went there. They have just three steps highlighted in a big bold red typeface. Nice and simple. I followed the steps and was up and running in five minutes. My blog was started. I haven't returned to WordPress since. I won't either, unless Blogger seriously lets me down over the long haul. when I went to WordPress to start my blog, I was overwhelmed. Having a ‘Before You Install’ to read is bad. I just wanted to get started. When I began reading it, I fogged over.

I asked My Better Half about it. She didn’t even bother looking up. She told me to go to Blogger. I went there. They have just three steps highlighted in a big bold red typeface. Nice and simple. I followed the steps and was up and running in five minutes. My blog was started.

I haven’t returned to WordPress since. I won’t either, unless Blogger seriously lets me down over the long haul.

]]> By: Holly http://idratherbewriting.com/2008/08/01/the-myth-of-simplicity-and-complexity-in-help-authoring/comment-page-1/#comment-133258 Holly Fri, 01 Aug 2008 14:19:15 +0000 http://www.idratherbewriting.com/?p=1764#comment-133258 " . . . simplicity is in fact a complex undertaking." So true. Reminds me of the quote attributed to Blaise Pascal: "The present letter is a very long one, simply because I had no leisure to make it shorter." Hollys last blog post..<a href="http://dontcallmetina.wordpress.com/2008/07/30/microsoft-community-clips-record-your-own-video-help/">Microsoft Community Clips: Record your own video help</a> ” . . . simplicity is in fact a complex undertaking.”

So true.

Reminds me of the quote attributed to Blaise Pascal:
“The present letter is a very long one, simply because I had no leisure to make it shorter.”

Hollys last blog post..Microsoft Community Clips: Record your own video help

]]>