Linux Today: Linux News On Internet Time.
Search Linux Today
Linux News Sections:  Developer -  High Performance -  Infrastructure -  IT Management -  Security -  Storage -
Linux Today Navigation
LT Home
Contribute
Contribute
Link to Us
Linux Jobs

Top White Papers

More on LinuxToday


Linux Bug #1: Bad Documentation (part 2)

| | Comments (0)

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


Comment and Contribute



    (Maximum characters: 4000). You have 4000 characters left.