2007-09-18
Brane Dump — The Thoughts of Matt Palmer
In “Documentation – the chicken and the egg” [1], Matt Palmer wrote about the problem that noone writes documentation because noone reads it and that noone reads documentation because the few documentation in existence usually isn’t very good. So he, like me hs the habit of searching for help on the net instead of in a projects documentation.
However I disagree with him in the consequences a bit. Because I noticed that on several projects with good documentation (subversion is an example that immediately comes to my mind, but postfix isn’t too bad either), the internet search returns a reference to the docs more often than not. Of course, this means that the documentation needs to be searchable for those webcrawlers. So if you have the task to write documentation, I strongly suggest to make it searchable in some way. For company-internal projects, this obviously means that the documentation must be reachable via an internal search engine. In a project a few years back, we implemented an internal search engine which included company internal information (even with user based access rules so that each user only got those results he could actually access) as well as an external search engines results. It was closed source, but a pretty nice idea. It didn’t, however, index any locally (user’s desktop) stored documents, only what was on some company web page (but including .doc, .rtf, .pdf and the like which where retrievable via http).
[1] http://www.hezmatt.org/~mpalmer/blog/general/documentation_the_chicken_and_the_egg.html
See also IP addresses
See also Init HackFest / New init systems in Debian
See also Strange MySQL (5.0) issue with authentication
Permalink
