Page 1 of 3 123 LastLast
Results 1 to 10 of 22

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

  1. #1
    Join Date
    Apr 2020
    Location
    where the work takes me
    Beans
    246
    Distro
    Ubuntu 20.04 Focal Fossa

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

    Hello all,

    Feel free to disagree with this if you like, but I find it odd that some of the most integral programs are really lacking in the documentation department. For example, recently I have been learning about udevd, and the documentation is so basic to say that it's a pretty integral component of some Linux distro's. Compare it with the documentation for something like Apache2, postfix or bash and it's pretty lacking.

    Now I'm not complaining because all of this stuff is literally free in every sense of the word, but what I don't understand is why developer(s) would put so much time and effort into writing a sophisticated piece of software, only to not tell anyone else how to use it properly. Surely it's largely pointless at that point? Hypothetically one could write the most powerful and sophisticated program on earth, but if you didn't document how to interact with it for others then it's useless.

    I have heard before that the documentation for proprietary/commercial software is way beyond what a lot of FOSS projects can offer, which would be understandable. I'd like to hear what others think and have experienced...

  2. #2
    Join Date
    Aug 2013
    Beans
    4,941

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

    I guess writing documentations is boring for developers and often the users are experts so they can work things out so they just leave it at that, unless there is a substantial commercial user base like apache. I find a lot of software has incomplete, outdated and ambiguous documentation. Often after hours or days of googling and searching forums it turns out that I could have saved a lot of time if the documentation is just a little bit clearer, or a bit more up to date. The other thing I hate are the stupid mailing lists. What year is this? 1991? My eyes hurt just trying to follow the quotes within quotes. I find the format of github or gitlab much more pleasant for asking questions and reporting bugs.

  3. #3
    Join Date
    Apr 2020
    Location
    where the work takes me
    Beans
    246
    Distro
    Ubuntu 20.04 Focal Fossa

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

    Quote Originally Posted by monkeybrain20122 View Post
    I guess writing documentations is boring for developers and often the users are experts so they can work things out so they just leave it at that, unless there is a substantial commercial user base like apache. I find a lot of software has incomplete, outdated and ambiguous documentation. Often after hours or days of googling and searching forums it turns out that I could have saved a lot of time if the documentation is just a little bit clearer, or a bit more up to date. The other thing I hate are the stupid mailing lists. What year is this? 1991? My eyes hurt just trying to follow the quotes within quotes. I find the format of github or gitlab much more pleasant for asking questions and reporting bugs.
    I agree, definitely relate to the point about ambiguous documentation. Whenever I'm writing notes about something, I always use a very stiff and formal style, which can seem like overkill, but I know that at some point in the future I'll have forgotten a lot of it and will need a reference that can only be interpreted in one way. I think ambiguous wording in technical docs is sloppy.

    I get what you're saying about the user base being able to work it out, I find it a bizarre thing for developers to expect though. I always relate things like this to mending cars, because that was my first love; a car is a physical thing and often not so complicated (although obviously more so as time passes) because many of it's systems involve physical concepts like combustion, gearing, friction, hydraulics, etc.. These are all intuitive things and relatively easy to understand because they are physical, just like we as humans are physical. In addition, broadly speaking almost all cars/trucks/vans are the same, and the skills learned working on one are directly transferable.

    contrast that with computer programs which are inherently opaque (even FOSS is opaque for someone like me who only knows a tiny morsel of one or two programming languages). Short of just trying things, the documentation is really all a lot of people have to guide them; a program can't easily be inspected like a physical thing could be. Furthermore the slightest syntactical error or misconfiguration can just break the whole thing, so I find it bonkers that anyone who is writing a program that they intend others to use en masse would skimp on the documentation! It completely undermines all their efforts. It's not a complaint, just an observation.

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

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

    The udev team left the building about 10 yrs ago and handed over the code to the systemd team. Udev was never meant to be touched by end-users. It is for admins and distro makers. I've touched udev once in my entire 25+ yrs on Linux.

    It was to get a new phone recognized as a USB storage device on connection. Every phone/tablet and other devices that I've ever connected which just worked without any modification to udev. Or they didn't work - ever. I was shocked when a USB slide/negative scanner just worked that hadn't worked since Windows Vista. No 64-bit drivers were created for it and WinXP was the last Windows software for it.

    I just scanned the udev, udev.conf and udevadm manpages. Seems there is plenty of information for using those tools. But I didn't try to do anything, so the documentation could be lacking or wrong.

    Apache does 1 thing. It serves web pages. That's relatively easy compared to udev which is basically a plug/driver manager for any sort of device that might ever be connected to a computer. There must be 20,000 different USB devices that might be connected, each is just a little different. Plus, many never planned on anyone using Linux with their devices. Apache was always intended to be used on Unix-like OSes, since the beginning.

    Now that the systemd team owns udev (they accepted the code so it wouldn't be abandoned), perhaps the detailed documentation is on freedesktop.org? I didn't look, but https://www.freedesktop.org/software.../man/udev.html All things in Unix require some background. When we are self-taught, it is common to miss very important ideas which makes learning how some things work much harder. Official training classes these days are forced to skip all sorts of concepts, since they are usually 1 week of intensive subject coverage, not the years of deeper knowledge that can only be gained by working with a mentor. Unix admins still need to be mentored. There are just too many details to be captured in training or books or self-learned.

    I also remember being very frustrated when I was first trying to understand manpages. They seemed to be written in a foreign tong. Eventually, thanks to the other people in my team who refused to answer questions that were covered in the manpages, I was forced to learn to understand. Long ago, all manpages used to provide an EXAMPLE section. Then a bunch of people started trashing their systems by copy/pasting the examples without understanding, so almost all manpage examples were removed.

    Sorry, but I don't have a fix.

  5. #5
    Join Date
    Apr 2014
    Location
    Tucson AZ, USA
    Beans
    1,053
    Distro
    Ubuntu

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

    I also remember being very frustrated when I was first trying to understand manpages


    This was and still is my biggest problem. I usually resort to googling syntax for some things because the man pages are about useless for that. They tell you options you can pass but not the structure of the whole command in some cases. You are left to try various ways until it works. Sed is the biggest one for me.

    COMMAND SYNOPSIS
    This is just a brief synopsis of sed commands to serve as a reminder to those who already know sed; other doc‐umentation (such as the texinfo document) must be consulted for fuller descriptions.

    (ubuntu 20.04, assuming same everywhere). Kind of dumb. Why does it exist if it just tells you to go somewhere else. People say RTFM. The manual says go find texinfo. Where is that exactly?
    Last edited by Tadaen_Sylvermane; August 3rd, 2021 at 04:31 PM.

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

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

    Code:
    $ info sed
    GNU wanted everyone to use 'info' instead of man. They lost on the format but haven't given up trying. Every time GNU creates a manpage, they tend to add a "for more information, see the info".

    Code:
    $ man info
    to get a summary.
    Code:
    $ info info
    to get all the details.

    Sorta like
    Code:
    man man
    , which explains how manpages are laid out, have different sections, and the goal for manpages. Until someone actually reads the man manpage, they probably will not get all the information out of a manpage which is there and implied just by the format.

  7. #7
    Join Date
    Apr 2014
    Location
    Tucson AZ, USA
    Beans
    1,053
    Distro
    Ubuntu

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

    Foot, meet mouth. Thank you.

  8. #8
    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 Tadaen_Sylvermane View Post
    Foot, meet mouth. Thank you.
    Not really. I've had the same complaint about info. I see the GNU effort to push info pages like when a single protestor shows up to protest something that nobody else cares about. The issue is decided already, they just haven't given up. Info pages have been around longer than I've been using Unix and they are still a pain.

    IMHO.

  9. #9
    Join Date
    Apr 2020
    Location
    where the work takes me
    Beans
    246
    Distro
    Ubuntu 20.04 Focal Fossa

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

    Quote Originally Posted by TheFu View Post
    Official training classes these days are forced to skip all sorts of concepts, since they are usually 1 week of intensive subject coverage, not the years of deeper knowledge that can only be gained by working with a mentor. Unix admins still need to be mentored. There are just too many details to be captured in training or books or self-learned.
    I know what you mean, recently I completed the Linux Foundations "Introduction to Linux" course that is offered through edx.org. It's a 140 hour course that culminates in an open book test. I ended up scoring 99.7% over about 130 questions, but I honestly learned very little from it. The scope of the material was way too big and it just breezed over some topics that would realistically take a month or two alone to get to grips with. It also seemed confused about who it was aimed at, as it was advertised as being suitable for people with a "basic knowledge of computers" but soon winds up teaching bash scripting and configuring network interfaces from the command line, going into great detail about the old class A/B/C IP address space scheme, etc. In 2021 a "basic knowledge of computers" to me is being familiar with the established user applications and perhaps knowing how to install additional software, setup a printer etc.

    It was the sort of course I can imagine people would get given at work because their manager thought it would be helpful, say if they were making the transition from windows to a Linux distro, but is actually just a chore with not enough focus on the relevant concepts. I used it as a bit of a curriculum, and often broke off to research the topics in more detail, but honestly I've learned much more from just reading documentation.

    I also remember being very frustrated when I was first trying to understand manpages. They seemed to be written in a foreign tong. Eventually, thanks to the other people in my team who refused to answer questions that were covered in the manpages, I was forced to learn to understand. Long ago, all manpages used to provide an EXAMPLE section. Then a bunch of people started trashing their systems by copy/pasting the examples without understanding, so almost all manpage examples were removed.
    This resonates with me, for a while when I began reading official documentation, some of it was written in such esoteric language to the extent that some of the simplest points were totally lost on me. I'd read it three or four times and then suddenly have that epiphany where it just clicks, and I would think "why don't you just say that then!?" If I'm being honest I now realise sometimes it's necessary in order to avoid writing documentation which is ambiguous and open to interpretation, but other times I think it might just be a symptom of the way in which the developer thinks (programmatic/mathematical thinking). I've only been using Linux since the date that I joined Ubuntu Forums and, thankfully, I can read the docs with relative ease now (depending on the specific document of course).

    My biggest beef now is documentation which doesn't contain the information I need, give me man bash any day of the week, it's hard to read and takes a long time to find what you're looking for, but you can be 99.9% sure the information you need is in there. I just can't stand airy fairy, ambiguous and incomplete documentation.

  10. #10
    Join Date
    Jul 2007
    Location
    Tāmaki Makau-rau, NZ
    Beans
    Hidden!
    Distro
    Ubuntu Development Release

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

    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.
    BACKUPS are unsexy — until you discover you should have done one yesterday.
    Spare your nerves and do one before you upgrade or install.

Page 1 of 3 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
  •