Results 1 to 10 of 10

Thread: Why can't we have the manual we need?

  1. #1
    Join Date
    Sep 2013
    Beans
    6

    Exclamation Why can't we have the manual we need?

    Forgive the following rant.

    I've been running Linux since July 1998. At that time, I thought "half the stuff you need to know was never written down". And I was right. The problem is I am STILL right. If anything, the problem has gotten worse in recent years.

    I condensed this down from an old repair manual for a car:

    "These models feature four coil suspension (McPherson Strut design) and front wheel drive. They feature transversely-mounted 4 cylinder or V6 engines, with carburetors or fuel injection, depending on model. The engine drives the front wheels through a choice of either a 4-speed manual or a 3 or 4-speed automatic transaxle by way of unequal length driveaxles. The brakes are disc brakes at all four wheels."

    Can anybody produce a wiki like that for ubuntu? It might read like this:

    Ubuntu provides an initialization routine at /etc/rc/*, which loads daemons, initializes hardware, sets certain system parameters, loads password databases, and finally the GUI, discussed in the "general" section of this manual. There is a choice of either KDE 4.x or Gnome X.Y, which is set in the file /etc/x86/foorc. KDE and Gnome are covered in separate chapters. Separate root and user logins are not used as they are in other distros -- see the "users and permissions" chapter for information on "sudo". And finally the "apt-get" chapter will describe the mechanism for receiving patches and updates. Log files are kept in /var/log/* and can be viewed with any text editor or viewer.

    Perhaps server stuff like apache, or MySQL, or languages like python or ruby would be too advanced for these guides. And you wouldn't need a chapter on Office programs either. But a good primer on how the basic stuff ties together (kernel, init, users and permissions, mounting, log files) would help us learn why things don't work.

    Can anybody write such a guide?

    (Typing rpm -qpi (or is it -qpl?) doesn't help you understand the way the basic bootup, kernel and init processes work [for RPM-based distros]. It shows a few rc files though. I assume apt-get, dpkg or other installer has the ability to list files in packages the same way rpm does, and thus give limited help.)

    Seriously, can anybody write such a manual? It would help immensely !
    Last edited by JP_Rockagetty_III; September 28th, 2013 at 11:40 AM.

  2. #2
    Join Date
    Jun 2011
    Beans
    417
    Distro
    Ubuntu 12.04 Precise Pangolin

    Re: Why can't we have the manual we need?

    http://ubuntu-manual.org/ could be a start but kernel, init system are only interesting for advanced users, developers and administrators - average users do not care about this topic as long everything works. Every distribution is different and you have only to compare rpm based distributions and you will find a lot of different tools which get used - users should learn basic commands of Linux/Unix systems and they can work with most systems and not to be shy/lazy to use "your favorite search engine" can be helpful too.
    Last edited by Gyokuro; September 28th, 2013 at 11:34 AM. Reason: typos

  3. #3
    Join Date
    Jul 2007
    Location
    Magic City of the Plains
    Beans
    Hidden!
    Distro
    Xubuntu 14.10 Utopic Unicorn

    Re: Why can't we have the manual we need?

    There's already a help page on sudo here. For APT I'd start with the Debian wiki.

    If I'm not mistaken (and I could be) Ubuntu still uses a mix of Upstart and SystemV init stuff.

    In short the information you want exists, but it's spread all over the 'net. Collating it all would not be a small task.

  4. #4
    Join Date
    Nov 2011
    Beans
    1,558
    Distro
    Ubuntu 14.10 Utopic Unicorn

    Re: Why can't we have the manual we need?

    Writing good documentation, including manuals, is not a widely distributed talent. The author needs to combine superior technical knowledge and skills with superior writing skills, and wrap both of those in superior teaching skills.

    The state of Linux documentation reflects the scarcity of such people. Windows and OS X are no different.

    Publishers have released, and still release, books on Ubuntu and other distributions. The pace of development and change in Linux quickly rather quickly renders them obsolete.

    Finally, the Linux approach to building an OS platform -- many individuals working more or less autonomously on some small bit -- does not transfer to the world of authorship. If you want something more than a spotty hodge-podge collection of howto's written mostly by people who do not know how to write, explain, or teach (e.g., man pages) you need a single author and a good editor willing to devote month's of fulltime effort to the task, and then find a way to stay on top of all the revisions that Linux churn will generate.

  5. #5
    Join Date
    Mar 2009
    Beans
    1,333

    Re: Why can't we have the manual we need?

    Gyokuro and buzzingrobot are right. There is a combination of lack of interest by the average user and the lack of truly gifted documenters. To that I would add that by the time somebody documents it in that sort of detail, something will surely have changed.

    The best documenters need to focus on where the need is greatest. As the user gets more skilled they can find out more by looking at the system itself and asking questions from there.

    When I got curious about the boot process (right about 1998 or 1999) I typed man boot and then started from there. IMO that's just about the perfect man page for the boot process. It tells you where to look, but since each distro is a bit different it can't be too detailed or it will be inaccurate. Fortunately on most distros all the files are text files and you can use your favorite editor to go spelunking through your boot process.

  6. #6
    Join Date
    Mar 2009
    Beans
    1,333

    Re: Why can't we have the manual we need?

    As far as that goes, maybe if you feel there's a lack of good documentation you might consider writing man pages. Man pages are better IMO because they help all with online (as in on-the-computer online) documentation, distributions, and they're available online too.

  7. #7
    Join Date
    Jun 2008
    Location
    Across The Pond
    Beans
    778
    Distro
    Xubuntu 12.04 Precise Pangolin

    Re: Why can't we have the manual we need?

    Quote Originally Posted by buzzingrobot View Post
    Writing good documentation, including manuals, is not a widely distributed talent. The author needs to combine superior technical knowledge and skills with superior writing skills, and wrap both of those in superior teaching skills.
    Exactly! And since most of those needing the documentation are at some beginner level, the author has to be able to put the cookies on the bottom shelf, so to speak, and write in terms and illustrations a beginner can understand. Not so easy for a technical subject.

    I keep a my own list of links, picking up a bit here and a bit there, all to help me find answers when I have questions.
    "Everybody is ignorant, only on different subjects." Will Rogers

  8. #8
    Join Date
    Apr 2011
    Location
    Mystletainn Kick!
    Beans
    4,753
    Distro
    Ubuntu

    Re: Why can't we have the manual we need?

    Quote Originally Posted by JP_Rockagetty_III View Post
    Seriously, can anybody write such a manual? It would help immensely !
    You can.

    Get involved if something bothers you.
    Splat Double Splat Triple Splat
    Earn Your Keep
    Don't mind me, I'm only passing through.
    Once in a blue moon, I'm actually helpful
    .

  9. #9
    Join Date
    Jul 2007
    Location
    UK
    Beans
    16,867
    Distro
    Ubuntu Development Release

  10. #10
    Join Date
    Sep 2013
    Beans
    4

    Re: Why can't we have the manual we need?

    Along those lines, it would be nice if each man page would include a few legitimate examples of the command. Many list the flags but never show how to compose the entire command sensibly.

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
  •