Yes Users Matter
If you want other people using your software, that is. There is never perfect harmony between devs and users, but it’s much better to respond to questions with a pointer to a FAQ or a manual than to ignore them, or to crab at them for asking, or worst of all, tell them to Google or trawl mailing lists. Web, forum, and mail list searches are for edge cases and troubleshooting, not for basic howtos.
“Documentation” covers a lot of ground, from basic man pages to glossy four-color books. Let’s take a look at the different categories of documentation, and what is reasonable to expect.
man Pages
Man pages are awesome. I love man pages. They don’t require a graphical interface, which is nice when Xorg or video drivers are broken, they don’t require Internet (assuming you don’t have some weirdo distro that doesn’t install them), and you always know how to find them– type man commandname. Nice and easy. (We’ll talk more about these, and other ways to find and use documentation, in Part 3.)
Command Documentation
Whether this is in a man page or some other form, documenting all the commands and command options in an application is essential. I shouldn’t even have to say this. How else is anyone going to know them, telepathy? …
Read the rest at LinuxPlanet.com