| 1 |
On Friday 06 February 2009 10:57:51 Neil Bothwick wrote: |
| 2 |
> On Fri, 6 Feb 2009 07:46:02 +0200, Alan McKinnon wrote: |
| 3 |
> > Man pages are mostly written as reference documents. Like technical |
| 4 |
> > specs, they tend to list the capabilities of the app without giving the |
| 5 |
> > "bigger picture overview" as that is assumed to be known. |
| 6 |
> |
| 7 |
> That's right,they tend to assume that you already know what you want |
| 8 |
> to do and are just a means of finding the syntax to do it. The problem is |
| 9 |
> that for most software, they are the only documentation provided. |
| 10 |
|
| 11 |
And in the true open-source tradition, where the supplied documentation (aka |
| 12 |
man pages) is inadequate, someone else will write better documentation, or |
| 13 |
howtos, or publish "Dummies Guide to $ARB_APP" and let Google figure out |
| 14 |
where it is. |
| 15 |
|
| 16 |
If Grandma can easily use Google to find new shortcake recipes (an entirely |
| 17 |
reasonable thing for Grandma to do in this day and age), then it is not |
| 18 |
unreasonable for savvy users to have a look at the man page and say |
| 19 |
|
| 20 |
"Oh look, this is a technical doc. Let me ask Google where better docs are" |
| 21 |
|
| 22 |
... |
| 23 |
|
| 24 |
-- |
| 25 |
alan dot mckinnon at gmail dot com |
Archives