Is Linux Documentation Lacking? 769
eldavojohn writes "A number of blog posts are surfacing that are calling out the helpful open source community on their documentation. No, not the documentation for the highly skilled technical people, but the documentation from beginner to apprentice. A two-part series by Carla Schroeder lists bad documentation as 'Linux Bug #1' and advises users to use Google as the documentation. We've discussed before some of open source's documentation being out of date. Is it really as bad as these blogs paint it? Has it come down to using Google before a man page?"
Re:Of course it is. (Score:3, Informative)
> Of course it is.
Agreed, first tip for the "beginner to apprentice":
Learning to use the "man" command is important, remember that you sometime have to add a number parameter to get the documentation that you want to get ;-)
Ubuntu Community Docs are pretty good (Score:3, Informative)
Documentation lacking? (Score:0, Informative)
Re:Documentation lacking? (Score:5, Informative)
Wireless Howto
Roberto Arcomano berto@fatamorgana.com
v1.6 - July 31, 2002
Re:Documentation is very lacking (Score:5, Informative)
Re:Yes. (Score:4, Informative)
Writing documentation is hard work and is boring. It is also thankless.
Amen. But, believe it or not there are people out there looking to assist open source by doing tech/doc writing [slashdot.org] for it. The comments in that thread have some really good resources if anyone out there is in total despair or is curious how they can help out open source documentation. I probably should have linked to that in the summary but my submissions have been way too link heavy lately.
Re:Documentation is very lacking (Score:3, Informative)
>apropos [thing I want]
But Linux distros could learn a lesson from FreeBSD in this regard. The FreeBSD docs are nothing short of excellent, and standard for the entire system.
Re:Of course it is. (Score:5, Informative)
True - though something is lacking in TFA: there is a diff between hitting the docs for learning, and hitting them for troubleshooting.
The man pages are more for learning (you can troubleshoot with them too, but diagnostic info in them are going to be lacking, just like trying to rely on the Windows Help files to fix a busted Exchange connector). Odds are, a beginner/apprentice won't know what to do with 'em for fixing a problem unless he/she is a royal badass at general computing/programming practices.
For troubleshooting, you're gonna have to hit Google - you have better odds there that someone else had the same problem and posted it (and its solution). There was once a time when you could write up docs for troubleshooting and diagnostics, covering up to 80% or more of what most folks run up against.
It still boils down to upping your skills on the OS and on general practices, though.
Re:Documentation is very lacking (Score:3, Informative)
Well, the man pages are only supposed to give the formal parameters of the command. The actual use of the command in a given context are given by HOW TOs.
Re:Of course it is. (Score:2, Informative)
Huh? (Score:3, Informative)
Somebody modded this insightful? WTF?
Re:Well, No Shit (Score:3, Informative)
I don't do much coding, so I don't release a lot of code beyond some Perl or Shell stuff, but when I do, I prefer BSD licensing to GPL licensing. Maybe I just don't think my code is novel enough for anyone to want to hijack anyway.
Re:Ok then.. (Score:3, Informative)
I'd insert a blank CD in the CD ROM drive.
Windows would then automatically pop up a dialog asking me what I want to do with this blank CD - such as write files to it.
Re:Of course it is. (Score:3, Informative)
Re:Don't like man pages. (Score:1, Informative)
I completely agree. I use Linux about 99% of the time, but recently test drove FreeBSD. I was amazed that the man pages and FreeBSD HandBook actually had useful things in them! It was like expecting to find a spray painted wall and instead discovering Oscar Wilde.
Re:Documentation is very lacking (Score:3, Informative)
GNU info needs to just die
+1
The shell function makes "info" tad bit more usable to me:
info() { /usr/bin/info --subnodes --output=- "$@" | $PAGER; }
Re:Documentation is very lacking (Score:1, Informative)
Type apropos. It will show you what commands do a specified task.
apropos burn
gnomebaker (1) - an easy to use CD/DVD burner for GNOME
Re:Not mutually exclusive. (Score:3, Informative)
I'd argue that sending the uncompressed file is faster, because you don't need to waste half an hour writing an elaborate program.
Try 2-5 minutes. And it's then reusable. By now, I know that sequence of commands well enough I could probably do it in 30 seconds to a minute.
And it is actually meaningful here. The sooner I can get that image taken, the sooner I can wipe the drive, and the sooner I can get the machine back in the hands of the customer -- or myself, for that matter. The server can then sit there crunching for days, if I want -- and lrzip will take days.
AND it's non-user friendly.
Yes, it is. It's a non-user-friendly way of doing something for which a user-friendly way doesn't exist, anywhere, that I know of. That's the point -- again, if there's a GUI that'll do the same job, that is better for the average user. But having a commandline available is better than nothing at all.
And again, you need the commandline version anyway. Another example -- suppose I'm responsible for maintaining a large network, so I need to be able to do things like this automatically. That is, walk up to a machine, have it boot from the network (or from a CD), into a system which automatically sends an image to the backup server, then wipes it with a clean image -- then the backup server can have a cron job to flush old images after a week or so, when we're reasonably sure the user doesn't need any files from them.
Now, how would I build a scheme like that from a GUI? You could argue that it'd be nice to have a GUI tool to configure the netboot server, or build a CD image for me, but ultimately, such a tool is easier to write if it can just add a few commands to a boot script -- and even if such a tool doesn't exist, a half hour of my time to build that system once will pay for itself many times over, when multiplied over a network.
Replacing the CLI with a mouse improves usability.
It improves discoverability, hands-down. That's what commandlines suck at. This is a good point, right here:
without memorizing the commands or digging through a manual.
But that is not about usability, it's about discoverability and learning curve, which is only part of usability. For example: I already know how to navigate my filesystem with the commandline, move files around, etc -- it took me longer to learn to do this, and things like 'cd' and 'ls' aren't right there in my face to find, I had to read some tutorials, etc. Tab-completion isn't obvious, either -- these are all things I had to be taught in some way or other.
The result is, I'm faster with the commandline than I am with the mouse. Really. Using cd and ls, with tab-completion, is faster than pointing and clicking on icons of folders. And once I've navigated to where my iso is, typing 'wodim foo.iso' is much faster than right-clicking on the image, looking for an option to burn, and clicking through a wizard.
And that's without even considering scripts. Taking the above example, I usually do something like 'wodim -dao -eject foo.iso' -- if this ever got annoying to type, I could easily make a new, shorter command which would do just that.
Now, that's not universally true. I've used lynx, and I wish I had better keyboard control in my browser, but a web browser is still much better in a GUI. I certainly wouldn't argue that photo editing or 3D modeling would be better done with a commandline. Each has its usefulness.
I also agree that if you're trying to do something simple, you shouldn't need a commandline. And this is mostly true on a modern Linux. Plug in your digital camera, and the appropriate software pops up -- that's even easier than on Windows, which makes you wait while it installs drivers, last I checked.
But to say that any need for the commandline is an indication of something broken is demonstrably wrong.