Women in Technology

Hear us Roar



Article:
  Is Linux Annoying?
Subject:   Documentation
Date:   2003-09-16 09:19:07
From:   anonymous2
Now I'm a real beginner with Linux, so maybe this annoyance will lessen with time and knowledge. I'm well aware of the wealth of information available about Linux (or GNU/Linux, for the purists...) The problem/annoyance is the level at which so much of this information is pitched. i can't give chapter and verse, but a humorous example goes something like this:


HOWTO for app XYZ-2.4.11


1. Clear comprehensible first step.
2. Clear comprehensible second step..
3. Gee I'm getting somewhere...
4. "Steps 4, 5 and six are trivial and not worth documenting since everyone knows and understands them...


Except me? So...


$ man XYZ
$ extremely logical and carefully crafted gibberish incomprehensible to newbies....


$ lynx http:// homepageforapp.org


more very logical advice incomprehensible to newbie...


Maybe I get lucky on a forum....but all this can be annoying....and maybe when I know more I can help by writing a simpler doc for the app in question. In the meantime.....AAARGH!


Full Threads Oldest First

Showing messages 1 through 4 of 4.

  • Documentation
    2003-09-26 23:29:01  anonymous2 [View]

    On a similar note, the documentation for many linux (and open-source in general) applications is missing one crucial element: What the program actually does.

    So many programs have manpages (or sourceforge pages) along the lines of

    -- voxflorb 1.2.4452 --
    Compiling voxflorb
    command-line options
    known issues in voxflorb
    etc. etc. etc.

    without saying anywhere what voxflorb actually does.
    • Documentation
      2003-10-11 15:51:25  anonymous2 [View]

      Well it voxes your florbs. Obviously.
      • Documentation
        2003-11-29 17:22:12  anonymous2 [View]

        Unless you call it with the "-i" flag. Then it will do exactly the contrary.
  • Very true
    2003-09-16 13:09:34  anonymous2 [View]

    your point is 1/3 of the documentation problem with the average Open Source project. One other is lack of documentation or just lack of updated documentation. The third is unclear pointers or links to documentation available.

    Consider PostNuke. Where is the documentation? Why isn't the main (navigation by their terminology) page better laid out? Where is "about" and where is "documentation"? Once you search through the forums you sadly (yet typically) you see snotty posts that basically say RTFM and that "the docs are included in {$rootdir}/pnGuide" yet guess what? THEY ARE NOT! And the fact that PN devs say this recently only shows their ignorance in their own product and thus a lack of communication. Next you look around for the FAQ. My but isn't that thing completely unintuitive in its "organization" and completely goes against accepted standards in layout and categorization? Oh, btw... you gotta find the correct FAQ as searching around will yield you various broken or empty links and other FAQ's.

    Eventually you discover that you must search elsewhere (besides the actual tool's home site) for that tool's documentation... huh? Why can't they at least link to it (once you actually find the link that is)?

    Hmmm, this says to look at "docs.postnuke.com" and now I ask why there was no direct link to this from the starting page "www.postnuke.com". Then when I type that in the navigation bar of my browser I see why: the doc site lists documentation links in a story submittal manor (think slashdot) and very much by chronological order only. You have to be familiar with the term, "Sections" and their unintuitive and inconsistent manner of categorizing various documents to track what you want down. No wait... you still can't find it because it does not exist locally. (hint: nothing is wrong with date sorted elements but ALWAYS have a clear, unhidden link to or list of CORE DOCUMENTS). Go to Gentoo.org. It is not "bad" if they list how to set up a Cisco router to talk to your Gentoo box and how to brew Bock beers at home. However, those things are secondary to the point of the site... Gentoo. Gentoo core docs (Setup, tool Core Tool explantions, and basic guides) are clearly available by clicking on a Docs link. They are well organized and kept up to date. More importantly, the Gentoo system is WELL DESIGNED and not hacked together. They have a clear idea of where they want to go, even if that is not a location but a direction. And yes, there IS a connection between planning/coordination and how things are presented. The bad designers fail to take into factor inevitable changes and their web site and tools reflect this. Out of date, non existent, or broken links to resources along with a disorganized chaos of partially completed resources mixed in at various points of the site. Its like walking into a grocery store and having Milk be located in 7 different locations, some of the cartons opened, others just years old and now a cheese substance.

    Here we see both in design/implementation and presentation/documentation the good and the bad possibilities of Open Source.

    I am not picking on PostNuke, but clearly their attitudes need adjusting to factor in their own lack of organization and clarity. Bitching at newbies frequent questions is silly when you don't update your FAQ, update your docs and actually make them available. It is highly foolish if your pop-off answers to newbies are not even correct.

    Oh and about those API docs... they don't work. Try actually using your own tool sometime to see how it is working and don't ignore feedback about is failure. For that matter, how can you expect serious professional developers to respect a tool that itself does not work on your site. (i.e. why do I have to relogin to each and every site... think about a data bridge and single sign on) PostNuke's other method of being an example of bad Open Source is in its marketing.

    Most get tired of dishonest and/or clueless company's marketing consisting of lies and inconsistencies. Open Source should tell it like it is, and let the developer or user pick the right tool for the job. Don't call your tool (PostNuke) a Content MANAGEMENT System (CMS) if your own site does not manage content decently and the team clearly does not abide by the philosphy of computerized management of information.

    PN is a blog and gaming clan site... those that have adapted it and claim it is therefore for prime professional web application development and things like E-commerce are confused. Those arguments they give would then say that a hacked together soap box racer made of plywood and cardboard thus means that cardboard and plywood is "the tool for automobile manufacturing."