Documentation, manpages, and examples
 

So, since I usually need help with programs, the first thing I typically do is Google something. I find a bunch of posts that may or may not have people replying to a newbie "Why do it this way when this other way is so much easier?" (typically found when compiling something from source on something like Ubuntu), or "If you used this distro, you could do this." (I've gotten a reply like that, and it is somewhat irritating). So, Google didn't help me. These types of things typically don't happen on a mailing list, but they do I forums. At least, from what I have observed.

So, I then go to the manpages or infopages of a program, perhaps something I should have done first. Then I get to go and hack through documentation just to find out that one little thing like getting white text on a black background in xterm, because for some unknown reason it's an annoying black text on a white background, but the documentation is extremely obscure. Sometimes, if I can't get it, I finally ask someone in forums, and nobody helps me or people recommend distro X to me. Either everyone hates me, or I just have bad luck. But, when I do read the documentation, it takes me two, maybe three readthroughs in order to grasp a vague concept, and then finally nail it down with some trial and error.

But, why?

The biggest problem is lack of examples. I find that examples help me tremendously more than any amount of documentation could, except where the documentation defines exactly what I need in conjunction with an example.

Let me take an example: Grub. It's documentation is good for someone who needs to know very specific boot options, but I haven't found anything in the documentation that gives a specific template like:

In fact, I find myself usually going back to the documentation, then remembering it sucks for a generic boot, and then I go and Google for an example then modify that to my needs. If Google fails me, then I go to a preexisting system and view what I had on there. This is usually when I am setting up a new *nix system.

But, why is it better? Because it explains syntax concisely, and the user doesn't have to type it all out (copy+paste+modify). There are downsides, though. It could be less likely to get memorized since the user isn't typing all the commands out, and the user could be prone to overlooking the documentation entirely. And if the user needs to do something special, they may be out of luck. So, maybe it isn't better, but just different. Different tools to explain different things.

I just have a question for all of you: What are your thoughts? Should generic or specific examples be included in documentation? Or should documentation be a bit clearer for the less technical users? Both?

I find that a little bit of both would be helpful. An example somewhere in the middle or end of a manpage, or template config files readily available would be nice. I've found myself lost in the TWM documentation and found an example config file very helpful when I was a bit too lazy to get a new window manager.

I've always liked examples that come with man pages. As far as being generic or technical, I guess it all depends on the topic and what you think the level of abilities the audience will be that is reading the information. IMO, a greate example of man pages are OpenBSD's.

http://www.openbsd.org/cgi-bin/man.cgi

One thing I will say is this: if you are unhappy with the documentation out there (and you are not alone) do something about it. Ever since I started using it, the world+dog has complained about the docs. But if they're still poor, that shows that no one has had the will to step up and fix the problem.

The other issue, though, is that there are so very many things you can do with the tools, that putting examples out there could be a lifetime's undertaking. The other option, then, is to open a blog and post your own examples. Make each post easily findable by Google and then you may start a groundswell.

The other option is to stick to the books, most of them have loads of examples, though they may not be the ones you need.

I would go with the blog option personally, that way you're not limited as to space.

I like the man pages real well just as they are. They do take a little studying to understand, but they are intentionally terse. The most possible explanation in the least possible verbiage.

Here's a tip, though. When you really can't figure our what you need, try goggling "man <command>". I usually find expanded man pages put together by some group or other with more verbose explanations and examples.

One question. Do you know how to use google search operators, (filtering search results, searching on specific site, searching for a phrase, for a word in page url, etc)?

1) In my opinion - documentation shouldn't be "less technical" or "adapted for non-technical users". It should remain the way it is now. I think so, because learning system in "difficult way" (by reading documentation, manpages, googling - just to get X running) was very useful for me, and helped a lot later. Basically for me (with a very little initial Linux knowledge) it took a month to understand my distribution to some basic level, and after that I could solve 98% of problems myself. If documentation was simpler, then learning system would take (IMHO) at least a year and even after that I wouldn't be able to solve most problems without assistance - because habit of digging information and solving everything myself wouldn't be created. The adaptation for "non-technicals" will make problems for user later - he'll will have to learn all technical info anyway, so such documents will waste users's and maintainer's time without much benefit. So, I think documentation shouldn't be easier, because (for me) "easy" or "user friendly" distributions take forever to learn how they really work.

2) You know, any user (including you) is free to make basic examples and submit them to package/software/disitrbution maintainers. But I don't think that many people are actually doing it (because user who "understands it all", won't need basic examples). Did you create any "basic examples"?

Yes. But, just out of curiosity, maybe I am bad at it, but could you tell me how to find which <http://www.xs4all.nl/~carlo17/which/> in Google? Probably the worst package name I have ever searched for. I had to use portage on my other box to find it. The knowledge that I have usually allows me to find anything given enough time.

The only clue I had was a program stop since it couldn't find which.

Good point. I know I learned a lot more trying to make Gentoo work than using Debian. And I learned a bunch more on LFS, even though the build documentation is basically copy+paste if one hasn't the willpower.

I do every time I reconfigure my comp, which is probably once every one or two months. But, maybe I will make some basic examples, and as someone suggested earlier in the thread, make a blog for it. But, I mean, sometimes that wonderful Ubuntu install does screw up so one has to boot a rescue CD, navigate around with the little command-line that one knows, and then try to fix the install by setting the grub.conf straight. A basic example definitely helps with that. But that is an extreme case. Maybe I just need to memorize Grub commands and the process in which is does things (which I think I have down now).

I think I made this because I was way annoyed with some of the documentation. I guess I could do more to help like understand the program better and rewrite the documentation a bit.

The trouble with Documentation is that you have to understand the application before you can write decent documentation for it. But once you understand the application, writing the documentation is boring.

Years ago I wrote a thundering great big Oracle database-based application:

Learning and installing SCO unix was fun :)
Learning and installing Oracle was fun :)
Configuring Oracle, writing, testing and debugging the application was fun :)
Triple-checking the security features was fun :)
Writing the UserGuide for the users was boring :(
Writing the Sysadm guide so someone else could maintain the system, restore from my automatic backups, write enhancements etc. was extremely tedious :( :( :(

So I quit developing software for other people :)

And now I do not complain about "lack of documentation". If there's anything, I am grateful.

even without advanced operators:
1) which unix brings you directly to a wikipedia article about "which" command. That article has link to official gnu page for "which"
2) GNU which brings you directly to the program website.

I'll try to explain that:
Imagine that we are looking for info about "cat" command
1) let's think a bit. We are not interesting in bulldozers/trucks/excavators (#1 hit on "cat" query), cat pictures, "felis catus" article, or "center of american technology". We are talking about cat program, running in shell on Linux/Unix, and program is created by GNU, and it have "manpage". So now we have potential keywords "cat", "shell", "program", "Linux", "Unix", "GNU", "man page". But not all those keywords are good. Imagine that you are trying what are you looking for in the least possible number of words, in such way that no other object exists that could be described with same words or have same words associated with it. This short and unique descripion might be what you need to feed to the Google. Or you can use words that only occur together on the page you are looking for (helps when you are looking for a particular page you saw before, but can't find now). Let's select good keywords and throw away those that won't help:
2) "cat" have several meanings - an animal, several acronyms, and program we are looking for. Alone it isn't good keyword, but we can't throw it away because it is the name of what we are looking for.
3) "shell" have several meanings - a CLI command interpreter, something like "turtle shell". This keyword won't make search easier, because shell doesn't solely mean "CLI shell" or "UNIX shell", shell isn't directly related to the cat command, so using it won't make search easier. (try "cat shell" and see what you'll get). There is no point in using that keyword.
4) "program" also isn't that good since it might mean something like "social program", "software" and bunch of other things. This keyword is too weak, and so it is useless. You can check it yourself - searching for cat program brings you to "Centers for Advanced Technology Program"
5) "Linux", "Unix", "GNU", "manpage". Now those are good keywords. They are directly associated with your platform, and the area your "cat" belongs to. Although using them all together (GNU linux unix manpage cat) will bring you to the wikipedia article about "cat program" (which mentions that "cat" is a part if "coreutils", so you'll be able which will lead you to the GNU coreutils website), using one of them should be enough.

So in search for "cat" cat unix will be enough to find information. (you can further filter results with cat unix -tutorial, for example.

I hope this explanation will help. Searching might be tricky, and sometimes requires a lot of thinking about "right" keywords, but when you'll get the idea, it'll be no problem.

Contacting package maintainers would be better, IMHO, because if they'll accept your tutorials, information will reach more people and it'll be more useful, than blog.

For my experience solving problem by searching for answers in some cases is more difficult on Ubuntu. That's because although distribution is popular, it's (unfortunately) designed to be user-friendly. IMHO, being user-friendly OS means that average user's skill is lower than on Slackware/Gentoo. Because average skill is lower, some questions will remain unanswered. I had several problems with Ubuntu which magically solved themselves during automatic update, but there were no ready-to-use solutions anywhere. This was especially true about "hardy heron" when it was just released. Solving problems with Google on Slackware/Gentoo should be much easier, i think.

I've been a bit ungrateful for the documentation that there is, and, I realize that. Examples would be good, but the documentation as it stands now is pretty nice if someone uses it to its fullest as it will probably stick to memory much better and have flexibility since one example can only apply to one or a few instances.

Hmmm... Sounds like I need to make a reference card to search for Unix, Linux, and GNU things. Maybe I just had a brain fart. I just usually don't have that much trouble.

It would have helped if I knew it was GNU package, though. Meh.


Yeah. The problem is that I will admit myself as a little (READ: very) lazy to commit myself to that. So, either someone else will do it or it will never get done.

Perhaps the documentation is better the way it is, how little documentation that there can be for some software. I've found documentation for almost any free software is much better than much proprietary software. Examples can be nice, but when someone should probably learn something, making examples on one's own is better--it sticks to memory much more easily.

I take it that this discussion is specific to commandline programs which are sometimes very difficult to understand and use effectively. The problem with examples in such cases is that everybody needs something different and UNIX command line tools can be notoriously complex.

Sometimes, I find that if I need a particular configuration, it's better to write a small shell script/Perl/Python script which wraps around the parameters required so that

1. I never forget it
2. It can be used conveniently

Or for something you really find complex, like I wrote a mencoder GUI front-end using TKinter and Python, try doing something similar for a program you find hard to use
(find my mencoder GUI here: http://hari.literaryforums.org/2008/...d-mencoder-gui)

That way not only do you learn the specifics of a program in and out, you can help other users understand the program and use it better.