Comments on: Nine things I learned about writing software documentation http://blog.nagarsoft.com/2006/08/05/nine-things-i-learned-about-writing-software-documentation/ Small Business technological experience at Nagarsoft Sat, 16 Feb 2008 08:24:36 -0800 http://wordpress.org/?v=2.8.4 hourly 1 By: Documentation Doctor » Blog Archive » You can stop now: Why documentation is no place for a message from our sponsor! http://blog.nagarsoft.com/2006/08/05/nine-things-i-learned-about-writing-software-documentation/comment-page-1/#comment-20 Documentation Doctor » Blog Archive » You can stop now: Why documentation is no place for a message from our sponsor! Thu, 12 Oct 2006 15:40:53 +0000 http://blog.nagarsoft.com/2006/08/05/nine-things-i-learned-about-writing-software-documentation/#comment-20 [...] You’ll note that the instruction is terse, without even a “simply…”. Since the feature really is easy-to-use, we can let it stand on its own merits. In fiction, this is known as show, don’t tell (something Andrea Nagar identifies as one of the rules of good documentation). [...] [...] You’ll note that the instruction is terse, without even a “simply…”. Since the feature really is easy-to-use, we can let it stand on its own merits. In fiction, this is known as show, don’t tell (something Andrea Nagar identifies as one of the rules of good documentation). [...]

]]> By: Documentation Doctor http://blog.nagarsoft.com/2006/08/05/nine-things-i-learned-about-writing-software-documentation/comment-page-1/#comment-13 Documentation Doctor Sun, 03 Sep 2006 10:08:21 +0000 http://blog.nagarsoft.com/2006/08/05/nine-things-i-learned-about-writing-software-documentation/#comment-13 [...] Something Andrea noticed – I’m a great believer in showing, rather than telling. [...]

]]> By: Andrea Nagar http://blog.nagarsoft.com/2006/08/05/nine-things-i-learned-about-writing-software-documentation/comment-page-1/#comment-9 Andrea Nagar Mon, 07 Aug 2006 16:19:42 +0000 http://blog.nagarsoft.com/2006/08/05/nine-things-i-learned-about-writing-software-documentation/#comment-9 Well, of course being a native speaker helps a lot. This is why I decided to have my manual revised :-) Dennis, apart from the term trigger (any suggestion on alternative words I can use?) I think that the second try is more direct. Well, of course being a native speaker helps a lot. This is why I decided to have my manual revised :-)

Dennis, apart from the term trigger (any suggestion on alternative words I can use?) I think that the second try is more direct.

]]> By: Dennis Crane http://blog.nagarsoft.com/2006/08/05/nine-things-i-learned-about-writing-software-documentation/comment-page-1/#comment-8 Dennis Crane Mon, 07 Aug 2006 07:32:06 +0000 http://blog.nagarsoft.com/2006/08/05/nine-things-i-learned-about-writing-software-documentation/#comment-8 For me, non-native English, the FIRST TRY is more understandable then the BETTER AS honestly. Most of non-techie and non-native English people may not know what does trigger means (I know though :-)): FIRST TRY: Direct Access associates words (called commands) to actions, so that when a certain word is typed, in any application, it can execute the appropriate action. BETTER AS: Direct Access enables you to specify words (called commands) to trigger actions whenever you type them. This works for any program. For me, non-native English, the FIRST TRY is more understandable then the BETTER AS honestly. Most of non-techie and non-native English people may not know what does trigger means (I know though :-) ):

FIRST TRY: Direct Access associates words (called commands) to actions, so that when a certain word is typed, in any application, it can execute the appropriate action.
BETTER AS: Direct Access enables you to specify words (called commands) to trigger actions whenever you type them. This works for any program.

]]> By: Fred http://blog.nagarsoft.com/2006/08/05/nine-things-i-learned-about-writing-software-documentation/comment-page-1/#comment-7 Fred Sun, 06 Aug 2006 22:39:23 +0000 http://blog.nagarsoft.com/2006/08/05/nine-things-i-learned-about-writing-software-documentation/#comment-7 Nice tips. Here's mine: 1. If you're not a native speaker, unless you're bilingual, forget about writing documentation. Natives will tell right away that it wasn't written by a native speaker. If it's a commercial product, they won't like it, and insist on having it written by native speakers. 2. Even if you're a native speaker, most people can't write, especially literary and technical stuff. It's a real job ;-) 3. Read the classic "The elements of style" http://www.amazon.com/gp/product/020530902X/ Nice tips. Here’s mine:
1. If you’re not a native speaker, unless you’re bilingual, forget about writing documentation. Natives will tell right away that it wasn’t written by a native speaker. If it’s a commercial product, they won’t like it, and insist on having it written by native speakers.

2. Even if you’re a native speaker, most people can’t write, especially literary and technical stuff. It’s a real job ;-)

3. Read the classic “The elements of style” http://www.amazon.com/gp/product/020530902X/

]]> By: Bob Walsh http://blog.nagarsoft.com/2006/08/05/nine-things-i-learned-about-writing-software-documentation/comment-page-1/#comment-6 Bob Walsh Sun, 06 Aug 2006 20:22:12 +0000 http://blog.nagarsoft.com/2006/08/05/nine-things-i-learned-about-writing-software-documentation/#comment-6 Nice post Andrea! Nice post Andrea!

]]>