If you develop open source software, or software that you give to the public out of the kindness of your heart, document it. I know people will say, “But it’s free! How can you add more demands on the caring, giving person who wrote it?”
Easily. Software that requires one to edit C makefiles because this little tweak or that little tweak won’t get picked up by the auto-configuration tools; J2EE applications that require tiny little tweaks in a dozen different text files; software that requires you ‘guess’ exactly what you’re supposed to do on a screen Are Not Helpful.
Undocumented APIs. Errors that provide no messages. No documentation because the developer is too busy building the next version of the software to write a silly thing like documentation. These Are Not Helpful.
I have worked with wonderful commercial and non-commercial, proprietary and open source software in the last several months for Practical RDF. These will all be included in the book, with full attribution for the creators as well as full appreciation for the good work and great software that’s a pleasure to both install and learn to use.
Software that is neither is not included. Simple as that. This evening I reached my Tweak/Fuss/Guess/Muck Overflow Point.
Archived with comments at Wayback Machine