Comments on: Helpless in Seattle http://brainsnorkel.com/2006/02/27/helpless-in-seattle/ Manifesto-driven development. Eclectic thoughts. Tue, 14 Feb 2012 13:12:08 +0000 hourly 1 By: Sunny Kalsi http://brainsnorkel.com/2006/02/27/helpless-in-seattle/comment-page-1/#comment-4900 Sunny Kalsi Sun, 12 Mar 2006 06:47:59 +0000 http://brainsnorkel.com/?p=241#comment-4900 Totally agree with Alastair. The first thing I thought of was PHP Manual too, because it shows both exactly how useless normal documentation is and how useful allowing users to enter documentation is for you. Whenever I read the PHP doccos, I'm always at a loss as to what they're actually on about. It takes a bit of rambling from users and some code samples to tell me what I need to do. I think the flickr forums idea is pretty good -- Don't document anything, but get the documenters to search the forums, fixing problems that users come up with. Often something that needs documenting would be better served by being more intuitive in the UI, for example. However, none of this works when the assumption of being connected to the internet doesn't hold. For this case, there still needs to be boring old doccos with a powerful indexing system which incorporates synonyms and grammar checks. Totally agree with Alastair. The first thing I thought of was PHP Manual too, because it shows both exactly how useless normal documentation is and how useful allowing users to enter documentation is for you. Whenever I read the PHP doccos, I’m always at a loss as to what they’re actually on about. It takes a bit of rambling from users and some code samples to tell me what I need to do.

I think the flickr forums idea is pretty good — Don’t document anything, but get the documenters to search the forums, fixing problems that users come up with. Often something that needs documenting would be better served by being more intuitive in the UI, for example. However, none of this works when the assumption of being connected to the internet doesn’t hold.

For this case, there still needs to be boring old doccos with a powerful indexing system which incorporates synonyms and grammar checks.

]]> By: Alastair http://brainsnorkel.com/2006/02/27/helpless-in-seattle/comment-page-1/#comment-4894 Alastair Mon, 27 Feb 2006 12:33:14 +0000 http://brainsnorkel.com/?p=241#comment-4894 Good stuff. As an example of the "self-correcting" help I really like the <a href="http://www.php.net/manual/en/" rel="nofollow">PHP manual</a>, which has an official reference for each topic, followed by a long thread of comments from users, usually to explain corner cases and the like. I'll note also in passing that the Docbook XSL stylesheets can generate Windows HTML help files as easily as they can generate plain HTML, or PDF, or manpages even (writing style differences notwithstanding). Lastly it should be said that from my experience the help doco is usually consulted only when something goes wrong. In my opinion most help systems spend far too much time on bleedingly obvious stuff like how to double-click the installer, and zero time on what "error -666, program aborted" means. This is the opposite of how it should be. Help doco writers should *start* with the error messages and work backwards to the easy stuff. OK that's hard. Howabout this then. Ensure that: a) the error messages are of sufficient quality (also hard, and possibly the subject of a blog post in its own right); b) the text of the error message can be copy and pasted; c) there exists a user forum in which the error message can be posted; and d) the alta vista spider can get to the forum. Is that too much to ask? **Posted by Chris after a Spam Karma dog ate Alastair's homework ** Good stuff.

As an example of the “self-correcting” help I really like the PHP manual, which has an official reference for each topic, followed by a long thread of comments from users, usually to explain corner cases and the like.

I’ll note also in passing that the Docbook XSL stylesheets can generate Windows HTML help files as easily as they can generate plain HTML, or PDF, or manpages even (writing style differences notwithstanding).

Lastly it should be said that from my experience the help doco is usually consulted only when something goes wrong. In my opinion most help systems spend far too much time on bleedingly obvious stuff like how to double-click the installer, and zero time on what “error -666, program aborted” means. This is the opposite of how it should be. Help doco writers should *start* with the error messages and work backwards to the easy stuff.

OK that’s hard.

Howabout this then. Ensure that: a) the error messages are of sufficient quality (also hard, and possibly the subject of a blog post in its own right); b) the text of the error message can be copy and pasted; c) there exists a user forum in which the error message can be posted; and d) the alta vista spider can get to the forum.

Is that too much to ask?

**Posted by Chris after a Spam Karma dog ate Alastair’s homework **

]]>