I tell ya, this Linux thingie just ain't gonna go, until...


Page 1 of 3 123 LastLast
Results 1 to 15 of 32

Thread: I tell ya, this Linux thingie just ain't gonna go, until...

  1. #1
    Join Date
    Mar 2007
    Posts
    98

    I tell ya, this Linux thingie just ain't gonna go, until...

    A few years back I was arguing in forums around the 'Net that Linux would not be embraced by the masses until at least a couple of problems were fixed - that is, Plug and Play support and bad/no documentation. The first is fixed - Knoppix and Ubuntu, just to name a couple, will recognise and install every device that I have, as long as it is not some brain dead "WinModem/WinPrinter" type of junk. (Now as far as the "masses" adopting Linux, I am not sure what the Linux community will gain if several hundred million non-technical icon clickers come on board, except maybe more driver support by manufacturers, but that is for another thread).

    As to the second problem (documentation), it is definitely not fixed. I know the reason (I am guilty of it also) - programmers hate writing docs, and programmers writing free GPL code have nothing pushing them to write it. So they (we) throw together a few pointers, call it documentation, and assume that the new user will have the patience to hack away until it works. Not always - several times in the past I have decided that trying to figure out how an apt was supposed to work, or be installed, wasn't worth the value that the apt was supposed to supply.

    Recently I helped a friend install a MUD game server application. I won't name it because its documentation is no worse than many other Linux apps. It was a very intensive application and apparently widely used. The problems...

    The abbreviated man page was useless with nothing but a few options for starting the program.
    The docs that were delivered with the package were empty skeletons. Nothing but "To Do" statements.
    The website documentation link had... you guessed it. "This document is under construction". Alas, the last date on the doc page was 2005, even though the last update to the actual application was only a month or so old which indicated that development was still active.

    I ran across one doc file that actually has the statement "I really need to write this someday."

    A dedicated techie who really wanted this to work would start taking scripts apart and using the old 'try and die' method of hacking away would eventually get it to work and know all about it when he/she was done. But most of us have other things that several dozen (or hundred) hours need to be used for.

    That is the no documentation problem. The other is bad documentation. This can be broken down into several types - too abbreviated, too technical, or pure sanskrit.

    Here is an example from the README for a utility apt...
    "...be warned that dynamic paging will cause an implicit ongrab, override with dograb or nograb." Wow, this is really great info for the intro section of a README file, especially since nowhere does it mention ongrab, dograb or nograb or how and where to use them. Are they command line switches and I need to put a "-" in front of them? Who knows? This, and a whole lot more, should be in the source at the statement that causes the problem.

    If I am actually looking for a README file, it means that I know nothing about the application yet and am trying to get it installed and running. Telling me that the fligit has to be mortificated with the glitzer module (use the -xyz switch unless your fleewarz is enabled) is of absolutely no help and sometimes can cause a knee-jerk reaction of apt-get uninstall, or RPM -e. Most Linux users are not programmers who can take apart the code in an application and figure out how it works - and don't want to be. Heck, I have trouble enough trying to figure out code that I wrote myself.

    Some package programmers genuinely try to supply docs, but they are almost always writing at too high a level. The main problem with this person is that they don't bother writing about the obvious, not realising that what is obvious to them takes hours of googling to make sense to their audience. The one program that I have published had what I thought was very in depth and easy to understand docs supplied - in fact, I spent a lot of time on them. But I still got gigged every now and then for "Insufficient/incomplete/confusing documentation."

    Note*** None of the above is to claim that WinDocs are perfect, by a long shot - I defy anybody, including the original programmers, to install the early IBM Websphere or Lotus Suites by using the install instructions! This isn't just a Linux problem - when our local school district started using Delphi for computer science (years ago), the manual was virtually rewritten by the instructors because the beginners Help section was incomprehensible to anybody who wasn't an Object Pascal expert.

    Anybody remember the Heath Corp? They made wonderful electronic kits (Heathkits) that were not only high quality, but the associated documentation was award winning. I read that before a new kit hit the market, a non-technical person (like a secretary, maybe) was given the kit to put together. So that where the instruction of "Install diode D1 with the cathode toward the top of the printed circuit card" made plain and totally unambiguous sense to the designer engineers, the novice might ask "What is a cathode?". Then the instruction would be changed to "Install diode D1 with the cathode (the white bar) toward...).

    Now, Linux users probably don't want a comic book approach to documentation - if they were that type they would be using Windows. But even a guru usually needs something besides a few lines of cobbled together programming notes.

    So, the above is a list of complaints. What are the answers?

    I don't know. If I PURCHASE a software package, I have the right to throw rocks at bad documentation. But, with Linux, we are usually getting high quality software that is both free and Free, and it would be highly impolitic to b***h about the lack of something - somewhat akin to loudly complaining about a birthday gift. But developers need to realise that better docs might cause a far higher acceptance of their work. Especially when you are trying to convince your IT director that a particular Linux utility is solid, free, and a perfect fit for the organization.

    You. "This Linux utility is solid, free, and a perfect fit for our organization."
    Him/Her. "Great, let me see the manuals."
    You. "...Uh, Well, it just has this 12 line README file... But the actual documentation is coming REAL SOON."
    Him/Her. "Get out."

    Konan

  2. #2
    Join Date
    Jan 2001
    Posts
    517
    Well, one idea that springs to mind immediately is to contact the developers of the code. Most of them have contact details.


    Surely from all these, you can find one that is well-documented and/or has helfpul developers?:

    http://www.linuxlinks.com/Software/Games/MUD_MUSH_MOO/

  3. #3
    Join Date
    Nov 2002
    Posts
    205
    Thats a pretty interesting point you bring up. It would probably be much more interesting if you actually mentioned the app names you are having issues with. I don't think you are going to hurt any feelings there. I say this because I honestly believe that there are more projects with docs than there are those with none.

    Especially when you start bringing into the argument business level software. Of the stuff i've setup at that level, apache, squid, ssh, samba stuff...that sort of area(obviously not at all comprehensive) the documentation has been more than adequate. I'd be a bit surprised of an application of that level to have 0 documentation.

    I tried to find the programs you were talking about to see what the deal was but all the muds at the top of google seemed to have docs, and the quote you mentioned from the "utility app" only really brought this post as a result.

    Basically, i think if you want answers you're probably being a bit vague yet.
    but really, i dont know what im talking about.

  4. #4
    Join Date
    Oct 2002
    Location
    Denver, Colo.
    Posts
    291
    I have to agree with Konan, many of the applications I've installed, wanted to use, have had very terse and some what poor docs. Don't have any examples on this machine, but things like " use the -c switch to do what you need, that's cool, but when it doesn't, and you look for help, under construction, don't cut it. what to do?
    And for a fleeting second...I was not sure if I was a man dreaming I was a butterfly, or, a butterfly dreaming I was a man....Lao-tzu

  5. #5
    Join Date
    Apr 2003
    Location
    UK
    Posts
    1,180
    I disagree, most people don't read documentation, so it isn't important for the average user. The power user may be interested in documentation, but they are also capable of using Google to find information and it is quite rare for me to not find the information I need.

    Yeah when I started I often found man pages hard to understand and some of them are really lacking, but again most users won't be looking at them.

    The times I tend to suffer from not finding the documentation I need somewhere mostly lies in the less used more obscure stuff, the example you gave was a MUD game server, that definitely comes in the less used category.

    As always, the real issue for Linux is it being pre-installed, on computers, and you know what, this year it is starting to happen, in June this year in the UK Linux pre-install reached 2.8%, that may not be a lot, but it is a start and surely that figure will only increase in years to come.

  6. #6
    Join Date
    Mar 2009
    Location
    Perth AU
    Posts
    17
    I was cruising past my local PC shop, the other day, & in the display window was a budget PC for $495 - I think.
    What really stopped me, was that it had Fedora 9 on it

  7. #7
    Join Date
    Jun 2003
    Location
    People's Republic of North America (Former United States)
    Posts
    849
    I just have to comment on this. I actually think the state of documentation is good. It could always be better but I don't see anything fundamentally wrong with it. I do think there is a problem with people actually reading the documentation. I have a Windows sysadmin that I am turning into a Linux sysadmin (always fun and entertaining.) The guy is smart but he absolutely hates using documentation. He told me most Windows admins pride themselves on just figuring things out. Well, I'm a hybrid, I can speak Windows and I can speak Linux, so I totally disagree with him. Anyway, he comes to me on a regular basis and says things like "how do you find files in Linux?" My standard response is man find or man whatever. He grumbles and goes away. Oh and did I mention I only let him use Run Level 3? Well, I do. So, he has now learned how to look things up. He hates it but I'm the boss. It's a perfect relationship and he is learning.
    I equivocate, therefore I might be.

    My Linux/Unix Boxes:
    Home: Slackware 10, CentOS 5.3, RHEL 5, Ubuntu Workstation 9.10, Work: RHEL 5, CentOS 5

  8. #8
    Join Date
    Jan 2003
    Location
    Austin, Texas
    Posts
    683
    Oh and did I mention I only let him use Run Level 3?
    How deliciously evil -- I love it. But be careful, if your company is anything like mine (I won't mention the name, but it's a 3 letter acronym that is spelled I-B-M) you can get dinged on your security audit for having a system that doesn't implement a screensaver password...even if the box is set in run level 3 and is sitting at a login prompt at the time of the audit (and always does when otherwise not being used).
    "The author of that poem is either Homer or, if not Homer, somebody else of the same name."

  9. #9
    Join Date
    Jun 2003
    Location
    People's Republic of North America (Former United States)
    Posts
    849
    Quote Originally Posted by gamblor01 View Post
    How deliciously evil -- I love it. But be careful, if your company is anything like mine (I won't mention the name, but it's a 3 letter acronym that is spelled I-B-M) you can get dinged on your security audit for having a system that doesn't implement a screensaver password...even if the box is set in run level 3 and is sitting at a login prompt at the time of the audit (and always does when otherwise not being used).
    I only let him have a training environment. I won't turn a newbie loose with root on a production box, Dear God, No!
    I equivocate, therefore I might be.

    My Linux/Unix Boxes:
    Home: Slackware 10, CentOS 5.3, RHEL 5, Ubuntu Workstation 9.10, Work: RHEL 5, CentOS 5

  10. #10
    Join Date
    Nov 2002
    Location
    Houston, Texas
    Posts
    299
    "...Anybody remember the Heath Corp? They made wonderful electronic kits (Heathkits) that were not only high quality, but the associated documentation was award winning..."

    I agree with your Heath Corp. post. I have fond memories. And I also agree with what you say about Linux docs. Years of using Linux and I still think the docs are worthless. They're written for ubergeeks. Good going.
    Thanks,
    Loopback48

    Debian fanboy. And only Debian.

    http://www.debiantutorials.org/

  11. #11
    Join Date
    Apr 2009
    Posts
    2

    I have countless install disks of various Linux Distros

    The latest was kindof interesting Slax as it runs Wine installed. I used Sun VBox to install it and it worked - but at console where you log-on it says to install it to your disk - with a caveat - "for experts only" - use make-disk.sh or something similar. It told me nowhere in the world what directory it was in or how to use a bash command for the .sh extension. So much of Linux is based on typing in a command shell that at least for me - if there was a concise manual of instruction how to use bash beside type man xyz it might help. I remember myself that AT&T when they were a dialup company known as Worldnet had a website dedicated to explaining how to setup an internet connection from DOS if you wanted to do so and other internet related offerings. Tiring to read, but it explained itself. Heathkit I agree with.

    BTW I finally learned to type at the bash command line when I was in the directory where this mysterious make-dish.sh was ./ make-dish. In DOS I could have used if in C: and make-dish.sh was in C:\boot\etc\ - C:\boot\etc\make-dish.sh - it was a challenge just to learn the syntax to run from directory.

  12. #12
    Join Date
    Jan 2003
    Location
    Austin, Texas
    Posts
    683
    BTW I finally learned to type at the bash command line when I was in the directory where this mysterious make-dish.sh was ./ make-dish.
    A single dot just stands for the "current working directory". That is, if you cd into /usr/local then type ls . it is the same thing as typing ls /usr/local. So if you wanted to execute a command that is not in your $PATH variable you could type out the fully qualified path to it like:

    /usr/local/Trolltech/Qt-4.5.0/bin/qmake

    Or you can just cd into /usr/local/Trolltech/Qt-4.5.0/bin and type ./qmake. Or perhaps you were in the /usr/local/Trolltech/Qt-4.5.0 directory. Then you would have to type bin/qmake.

    If you do not like typing out these long directory names, then you can simply add the path where the executable resides to your $PATH environment variable (for example, export PATH=$PATH:/usr/local/Trolltech/Qt-4.5.0/bin). Then you can simply execute the command from within any directory, without the need to fully qualify the path or anything of that nature.

    There are security reasons why you should use ./ instead of putting the directory . into your PATH. I cannot give a reasonable explanation without typing more information, and since someone has already done all of this, it's just easier to link you to that web site. It also describes similar information to what I stated above.

    http://www.linfo.org/dot_slash.html
    "The author of that poem is either Homer or, if not Homer, somebody else of the same name."

  13. #13
    Join Date
    Apr 2009
    Posts
    2

    thnx Gamblor1

    I am an old DOS fan - I run XP2 as Vista does not like my Video setup - a Firewire and TV-Card, Linux picked it up nice - Wine needed for Xnews and VuePrint nothing in Linux equalling those two apps, and so Linux reminds me of a program called McShell95.

    It was a GUI run from DOS imitating Win95 if your computer did not have enough oomph to run 95 - which I believe was 4mb Ram - but could run on
    2mb. You could talk to it and create an Icon to the location of your DOS program you wanted. AT&T told you how to create a PPP connection through DOS - DR-DOS had the DOS browser Spider I believe was name and then there was Arachne and there were a couple others. Trumpet was the newsreader, and you dowloaded files having to use UUEdecode, etc.

    To do all of that you needed to know DOS. In Linux it starts you off at Root in comparison to DOS you are not at the root directory, but some middle point. Root in DOS means C:\ top of the directory tree. I know X is needed to run a graphical program - how long did I learn how to configure X with RedHat6 on an old computer with a built-in i810 graphic card. I have a real card on the computer now a GeForce and Linux just configures X now without a hassle. I want to learn how to run from a command prompt. create shell programs (.sh - which is a .bat equiv)


    so point me someplace.



    Thanks

  14. #14
    Join Date
    Jan 2003
    Location
    Austin, Texas
    Posts
    683
    I would suggest you start here:

    http://tldp.org/HOWTO/Bash-Prog-Intro-HOWTO.html


    Also, here is the follow-up "advanced" guide. In reality however, I recommend you try to read them somewhat concurrently. The "tests" section (chapter 7) I think should be studied right around the time you study loops (possibly before). if tests (and related else/elsif constructs) are insanely useful.

    http://tldp.org/LDP/abs/html/


    I just found this as well. I have never used it myself but it might be useful too:

    http://linuxcommand.org/
    Last edited by gamblor01; 04-24-2009 at 11:20 PM.
    "The author of that poem is either Homer or, if not Homer, somebody else of the same name."

  15. #15
    Join Date
    Apr 2009
    Location
    Idaho
    Posts
    5
    Konan is 100% correct. Anyone who says that documention would not be viewed by or beneficial to the general public is a RETARD!

    To Konan - your post was articulate and well thought out - from a somewhat newbie's perspective, I find linux to be mostly UNDOCUMENTED. Sure - I like a challenge, and figuring something out tends to make me feel good. However, spending six hours trying to figure out how to get a wireless nic working is just insane. I don't mind tinkering with something for an hour or two, but come on...... having to try 20 different solutions to make simple hardware do what it is supposed to do is completely lame. I have a life away from my computer - you know socializing, enjoying relationships, doing physical things, etc. Only a complete shut in with no friends or relations would think that spending six hours on a stupid task that should be done by the software automatically is a good way to spend a day.

    I don't care if linux is free - and if every piece of software that was ever written to run on linx was free. Without documentation and more automation - Linux will always be in 2nd, 3rd, or last place. More pressue needs to be applied to hardware developers from the users. I personally have sent very long winded emails to IBM, Atheros, HP, Compaq, and others regarding their lack of commitment to the linux community. Linux is definately here to stay, but I know of many people who have tried it only leave it out of frustration in a very short period of time. Personally, I have come to it and left at least eight times. I am now forcing myself to use only linux for a period of 60 days. Unfortunately, most people are not willing to do this - and I can understand why - it is not productive initially. Somebody once told me as I argued the merits of Linux with them..... "You get what you pay for". He was referring to the cost of most of the distrobutions of linux. While I would generally agree with him for most things, I think you get a hell of a lot more with linux than what you pay for, but hardcore linux users and fans need to remember that the command line WILL NEVER BE ACCEPTED by the general public. Did I say NEVER, because I meant to say NEVER EVER!

    As for documentation overall, linux is not the only guilty party. Developers do seem to have an aversion to documenting their code. I've always thought this to be dumb. If I wrote a cool program, I would want everyone to know how to use it and to spread the word. I guess caffine, nicotine, and late hours make a person less able to handle writing?

    Whateva

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •