davidgurvich, your statements can't help but remind me of some line posted somewhere in this forum about a "slackware box in the basement" running for over a decade without being touched. I wasn't sure if it was true or exaggeration but I would believe the former just as much as the latter >_>.
Quote:
Originally Posted by nihonto
scottro, you're right  !
But a lot of BSD man pages aren't perfect, too - especially, if one is looking for some basic information (and is not an expert!). Much often I have read man pages and after I knew as much as before. Why? Because a) quite often they are lacking structure (like starting with the basics and then proceeding to the more advanced tasks) and b) they are very theoretical.
...
And I think that it's sometimes because experts are writing for experts. |
Some manual pages are worse then others but most are fairly good in OpenBSDs case.
One time I was doing something in FreeBSD, the program kept giving me an error although I was doing it 'properly' as far as I understood the manual (along with testing every which similar way while trying to read the writers mind).
In the end I had to go look up the source code and mutter, "thanks for not writing an EXAMPLES section !#%!" !
When I was learning LaTeX I also read some good advice:
0/ Tell them simply and concisely what you want to tell them.
1/ Then explain it in detail
2/ Then give a summery of what you just told them, simply and concisely.
For both experts and people who are less experts, especially if you ever want to get anyone expert or not reading past the abstract or introduction.
I would describe my learning by "show me, then tell me" so manuals don't always cut it -- sometimes I need to quickly look up how to do X or my memory has one of those "Uhh, what switch does Y again?" moments.
So I like manual pages that put it in English and show you what the flib you are supposed to do without requiring a Ph.D. AND also manage to tell you everything !
That way, you can use the manual to get a quick understanding of it's operation and use the more detailed explanations to find out how to use it to best serve your needs.
A *good* manual page should be all someone needs and including examples in the documentation and in configuration files, so you don't have to push 20,000 things onto your brains stack when using the program really helps to do that !