Page 2 of 3 FirstFirst 123 LastLast
Results 11 to 20 of 22

Thread: Why do some of the most established programs have poor documentation?

  1. #11
    Join Date
    Mar 2010
    Location
    Squidbilly-Land
    Beans
    Hidden!
    Distro
    Ubuntu

    Re: Why do some of the most established programs have poor documentation?

    Quote Originally Posted by Irihapeti View Post
    Oh good. I'm glad I'm not the only one. I thought that man pages must be written in a fancy style that you only learn when you get a CS degree. You know, a bit like how med students have to learn all that esoteric medical terminology that the rest of us don't go near.
    For the first 6 months of reading manpages, I found them all difficult, then something clicked and they started making more and more sense. manpages aren't training guides. They are references for people familiar, who just need to look something up.

    In the old days, programs would come with a Users Guide, Administration Guide, Installation Guide. Each for a different type of reader. Manpages are split into different sections, each with a specific audience. There are admin commands, user commands, games, .... here's the list.
    Code:
           1   Executable programs or shell commands
           2   System calls (functions provided by the kernel)
           3   Library calls (functions within program libraries)
           4   Special files (usually found in /dev)
           5   File formats and conventions, e.g. /etc/passwd
           6   Games
           7   Miscellaneous (including macro packages and conventions), e.g. man(7), groff(7)
           8   System administration commands (usually only for root)
           9   Kernel routines [Non standard]
    If you need to modify a config file, the section 5 is what you want.

  2. #12
    Join Date
    May 2020
    Location
    top of the mountain
    Beans
    65
    Distro
    Ubuntu Development Release

    Re: Why do some of the most established programs have poor documentation?

    I've started using Ubuntu OS with Karmic Koala and from the beginning I have used the development version of Ubuntu as my primary OS. I used Puppy Linux for at least a year before that. I have encountered many problems over that time period and have become a very good "re-installer" using various methods depending on what was most appropriate for the moment. To this day I have not failed to find a solution to any problem that I have had with Ubuntu or in fact any Linux OS. Linux has a reputation for being a "techy" experience. That reputation by itself implies that there are a lot of really smart and experienced users around the Linux world. Without question a new user will have to be able to follow directions and understand and know how to use google search. In many cases google search will bring a user right back to this forum. But understanding and following directions is a talent, a skill and qualitative. My very first customer died a few months ago that I supported with his network for twenty years. At the time just prior to his death he was paying me to answer the same questions he was paying me to answer twenty eight years ago. He was very successful at his business and was task oriented with his software. But regarding the internal workings and problem solving of the system and software he had nothing going at all. I think the information available for most problems are adequate. The users that we have that can explain to others how to use that information I think are a blessing. Today I'm using Ubuntu Impish with Gnome 40.2 as my primary OS and as always have an updated reinstall disk near by.
    Last edited by zebra2; August 8th, 2021 at 04:16 PM.

  3. #13
    Join Date
    Aug 2013
    Beans
    4,729

    Re: Why do some of the most established programs have poor documentation?

    That may also have something to do with the geeky personality of the devs. I know a few real geeks and they are the poorest communicators ever. You ask them some questions and they would go into details and commands without explaining what those things are supposed to do (or how to undo things, which is very important and is missing from a lot of tutorials and how-tos) No high level conceptual explanation ever, just details and jargon without proper definitions, lots of which probably irrelevant to the problem. In one aspect they tell you too much irrelevant details but often they are missing the key parts that you do need to know. Now imagine these people translating their rambling into manual. I used to teach math, if I explain things like that to my students they would have thrown me out of the window,
    Last edited by monkeybrain20122; August 8th, 2021 at 07:18 PM.

  4. #14
    Join Date
    May 2020
    Location
    top of the mountain
    Beans
    65
    Distro
    Ubuntu Development Release

    Re: Why do some of the most established programs have poor documentation?

    +1 post #13

    The instructions are plentiful.
    The understand'ers are few.

    If all else fails, follow the instructions. (and keep an install disk nearby.)

  5. #15
    Join Date
    Mar 2010
    Location
    Squidbilly-Land
    Beans
    Hidden!
    Distro
    Ubuntu

    Re: Why do some of the most established programs have poor documentation?

    Quote Originally Posted by monkeybrain20122 View Post
    That may also have something to do with the geeky personality of the devs. I know a few real geeks and they are the poorest communicators ever. You ask them some questions and they would go into details and commands without explaining what those things are supposed to do (or how to undo things, which is very important and is missing from a lot of tutorials and how-tos) No high level conceptual explanation ever, just details and jargon without proper definitions, lots of which probably irrelevant to the problem. In one aspect they tell you too much irrelevant details but often they are missing the key parts that you do need to know. Now imagine these people translating their rambling into manual. I used to teach math, if I explain things like that to my students they would have thrown me out of the window,
    Communication is an issue with every expert in any field, not just software or hardware computer people. Try to have a conversation about Algebra with a Math PhD and even with 21 college hours of math beyond calculus, you can't talk. I've tried.
    Or talk to a botanist about their field. I've actually seen an IP networking expert and a packet network expert IN-THE-SAME room be unable to communicate using the same white board. Their worlds didn't intersect. After about 30 minutes of them sharing terms, a solution that would bridge the packet network onto the IP network was designed. 3 months later, we were deploying it.

    When it comes to learning the definitions, that's an ongoing effort for everyone. Very few people are interested in spending the time to get the required background skills to do even the most basic things. It is frustrating to people who actually did spend that time to learn those things. It probably took them years, yet someone else expects to learn enough in 2 paragraphs to answer a simple question - simple questions seldom have simple answers. That's the way of the world when there's no context around the question or who is asking and why.

  6. #16
    Join Date
    Aug 2013
    Beans
    4,729

    Re: Why do some of the most established programs have poor documentation?

    Quote Originally Posted by TheFu View Post
    Communication is an issue with every expert in any field, not just software or hardware computer people. Try to have a conversation about Algebra with a Math PhD and even with 21 college hours of math beyond calculus, you can't talk. I've tried..
    Actually you can explain some very advanced topics in mathematics such as topology and abstract algebra to even highschool students if you know what the key ideas are and omit the irrelevant details and mechanics. There are a few Russian mathematicians who are really good at that (e.g Arnold or Komolgorov if people know about these names) There are also very good popular physics (Hawking, Penrose, Greene etc) and biology (Dawkins) books for lay readers. Mind you, you won't become an expert or be able to read advanced textbooks after reading these, but at least you have an idea about the story. I think some subjects have a narrative, a conceptual framework (like mathematics, physics) Others are less so. Computer science can be very conceptual too if you go into "abstract" fields like computability (which is basically discrete mathematics and logic) but the application areas are more procedural driven, you do a, b and c then d works, a lot of rote memorization and seemingly random facts... There is probably a story behind that but many practitioners are not very good at telling it (or not even try as they tell you to RTFM) The mathematician David Hilbert talked about two types of learners: the conceptual learners and the procedural learners, I suppose many (most) coders are of the second kind on steroid.
    Last edited by monkeybrain20122; August 8th, 2021 at 10:26 PM.

  7. #17
    Join Date
    Mar 2010
    Location
    Squidbilly-Land
    Beans
    Hidden!
    Distro
    Ubuntu

    Re: Why do some of the most established programs have poor documentation?

    Quote Originally Posted by monkeybrain20122 View Post
    Computer science can be very conceptual too if you go into "abstract" fields like computability (which is basically discrete mathematics and logic) but the application areas are more procedural driven, you do a, b and c then d works, a lot of rote memorization and seemingly random facts... There is probably a story behind that but many practitioners are not very good at telling it (or not even try as they tell you to RTFM).
    Computer Science has very little to do with coding. About 50% of the CS people I know cannot code anything. That surprised me.

    Programming can be "lot of rote memorization and seemingly random facts", but that's the same as saying that Leonardo da Vinci was just a house painter.

    Isn't math mostly "rot memorization and seemingly random facts?" Didn't everyone get forced to memorize their "times tables?" When someone hasn't learned basic skills that arithmetic, but wants to jump into n-dimensional calculus, there's a bit of a disconnect. We see that in these forums all the time. It is easy to ask "simple questions" without any background, then become frustrated when the answer isn't 1 command, but 15-35 commands, each needs to be exactly perfect.

    And the manpages are still references, not beginning how-to teaching materials. If we read a manpage and don't understand the terms, then we, by definition, don't have the necessary background and need to learn those terms.
    Last edited by TheFu; August 9th, 2021 at 05:37 AM.

  8. #18
    Join Date
    Aug 2013
    Beans
    4,729

    Re: Why do some of the most established programs have poor documentation?

    Quote Originally Posted by TheFu View Post

    Isn't math mostly "rot memorization and seemingly random facts?" Didn't everyone get forced to memorize their "times tables?"
    Well arithmetic is not really mathematics, neither is accounting, it is like saying spelling is literature.

  9. #19
    Join Date
    Mar 2010
    Location
    Squidbilly-Land
    Beans
    Hidden!
    Distro
    Ubuntu

    Re: Why do some of the most established programs have poor documentation?

    Quote Originally Posted by monkeybrain20122 View Post
    Well arithmetic is not really mathematics, neither is accounting, it is like saying spelling is literature.
    To 99% of the world, arithmetic **is** mathematics.

    So, imagine trying to break up basic calculus into manpages that can immediately be put to practical, but exact, use by anyone who doesn't have any background in Theory of Limits. What would the SEE ALSO section contain?

  10. #20
    Join Date
    Aug 2013
    Beans
    4,729

    Re: Why do some of the most established programs have poor documentation?

    Quote Originally Posted by TheFu View Post
    To 99% of the world, arithmetic **is** mathematics.

    So, imagine trying to break up basic calculus into manpages that can immediately be put to practical, but exact, use by anyone who doesn't have any background in Theory of Limits. What would the SEE ALSO section contain?
    Who cares about 99% of the world, once upon the time 99% of the world thought the earth was flat and ghosts exist.

    Actually, Newton did calculus without limit. I once taught a calculus course to college students without limit but along Newton's idea of infinitesimals (basically ignore all higher power terms, technically called o(x^2), and you recover all the usual formulas) These are quantities too small that can be ignored in first order approximations. Basically a lot of American highschool textbooks do try to break up calculus into man pages and they are terrible with emphasis on mindless computations and plugging numbers into formulae but little conceptual development. Well you can do all these with computer algebra packages like maxima these days so those are mostly obsolete skills.
    Last edited by monkeybrain20122; August 9th, 2021 at 11:27 PM.

Page 2 of 3 FirstFirst 123 LastLast

Tags for this Thread

Bookmarks

Posting Permissions

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