Comments on: Bad Documentation is a Killer http://www.sitepoint.com/blogs/2008/02/21/bad-documentation-is-a-killer/ News, opinion, and fresh thinking for web developers and designers. The official podcast of sitepoint.com. Mon, 01 Dec 2008 19:33:08 +0000 http://wordpress.org/?v=2.5 By: diva #2 http://www.sitepoint.com/blogs/2008/02/21/bad-documentation-is-a-killer/#comment-641200 diva #2 Fri, 22 Feb 2008 01:22:46 +0000 http://www.sitepoint.com/blogs/2008/02/21/bad-documentation-is-a-killer/#comment-641200 If you want to write good documentation, test early and test often. After publishing, don't dump and run. Allow avenues of feedback (like this comment box) and encourage feedback. Keep updating the doc based on the feedback you get. If someone has trouble because they missed a step, make the step more noticeable. If they misunderstood something, rewrite it. Listen to your readers. If you want to write good documentation, test early and test often. After publishing, don’t dump and run. Allow avenues of feedback (like this comment box) and encourage feedback. Keep updating the doc based on the feedback you get. If someone has trouble because they missed a step, make the step more noticeable. If they misunderstood something, rewrite it. Listen to your readers.

]]> By: cranial-bore http://www.sitepoint.com/blogs/2008/02/21/bad-documentation-is-a-killer/#comment-641022 cranial-bore Thu, 21 Feb 2008 13:32:19 +0000 http://www.sitepoint.com/blogs/2008/02/21/bad-documentation-is-a-killer/#comment-641022 I've recently spend a bit of time using PHPDocumentor to generate developer documentation for the first time. I can see that I should do it from now on. Funnily I've been using the comment style required by this package in my source code for more than a year, in anticipation for when I'd start :) I'm a little less clear on systems to help produce less technical end-user documentation. I guess a CMS with a plugin to render static HTML files or a PDF for easy transport would be good. I’ve recently spend a bit of time using PHPDocumentor to generate developer documentation for the first time. I can see that I should do it from now on. Funnily I’ve been using the comment style required by this package in my source code for more than a year, in anticipation for when I’d start :)

I’m a little less clear on systems to help produce less technical end-user documentation. I guess a CMS with a plugin to render static HTML files or a PDF for easy transport would be good.

]]>