Randy; I hate to say this. BUT: If your post was a complaint about documentation being too wordy, it was lost in your note, being too long & wordy. Sorry.. I stopped reading about half way through, when you atarted explaining the same thing.. again.
Ric On Tue, 2002-02-05 at 06:20, Randy Kramer wrote: > Ric Tibbetts wrote: > > <rant> > > So, at the risk of starting a flame war: > > > > Why does nearly everything with Linux need to be a work-around? > > It would be nice if things worked the way their supposed to, without > > requiring a bunch of hacks, and work-arounds. > > That is my single biggest complaint about it. It's often very > > discouraging. Esp. when friends are over (the devout windows people), > > and I go to show them something, and I have to go through a series of > > hacks to make something work. It really takes the steam out of the demo, > > and keeps us firmly planted in the "hackerware" catagory. > > </rant> > > <continuing the rant> > Interesting question, and one I'd like to consider the answer to and try > to change the answer. > > There are several perspectives on this, and in the following I am > probably only going to address one or two: > > First: > Some of it is my own fault, as I will freely admit and others will be > happy to remind me -- I should RTFM: > > * But in the dos / Windows world, I read a lot of TFMs, and am now > tired of reading TFMs, but find that too little of what I learned in > Windows is useful in Linux > * When I do RTFM, (and I'm thinking of books or articles written > about software (I didn't express that well, but I'm trying to say > something like "secondary sources")), rather than the "primary sources" > like the RFCs or the manuals associated with a particular software > product, I find them either too sugar quoted (too wordy, too flowery, > too cute, ...) (I start reading, then skimming, because I don't find the > answer to my questions -- soon I'm turning pages and barely glancing at > each, then I put the book down, and I'm missing the little tidbits that > show up every several pages or so that would answer my questions), or I > find them too detailed -- they print the entire source code of some > program, then include an incomplete line-by-line analysis of the program > that is as boring and annoying as the other extreme (the wordy, flowery, > cute, ... stuff). > * Once I had a certain body of knowledge in the Windows world, in > many cases learning a new application in Windows did not require reading > a manual. (Presumably the same thing will eventually happen for me in > Linux?) > > So I should start concentrating on primary sources, and I will. But, > there should be secondary sources that accurately summarize the primary > sources, without a lot of annoying extra words, or cute and flowery > language. Maybe the HOWTOs? (I've read a few -- unless I find one that > hits the thing I want to do head on, the same thing happens -- I get > bored and quit reading. ) > > (I'd like to assure you that I used to be a voracious reader, so this > quitting is not my typical reaction. Maybe (repeating myself) it's that > I'm now reading the same stories (how to do the same things), but most > of it is duplicate of what I've read about Windows, and only the details > have been changed (or, more accurately, are different) to make the story > correct for Linux. (And maybe I'm just getting old and lazy.) > > So, I'd like to find short concise documentation that deals with exactly > what I have to do without the flowery language or even explanations of > how things work in the computer world. (I learned (some of) those when > I learned dos/Windows.) > > Now, on to a similar but slightly different point. When I say I want > short concise documentation explaining exactly what I want to do, there > are at least two possible levels of doing this: > * If there is a GUI available to do this (whatever "this" is), > someone could detail the step-by-steps of the GUI (click on this icon, > double click here, blah, blah, blah). > * The step by step detail of using a GUI configuration tool is > somewhat useful, but, knowing that, in many cases, in the end the GUI > puts information in various text configuration files, it would be more > useful to me to know what changes have to be made in which files. > > Maybe the ideal step by step explanation of a GUI configuration tool > would mention what each GUI action did in terms of setting a parameter > in which configuration file? > > Ok, looking at what I wrote, I didn't directly address the point of why > "nearly everything with Linux need(s) to be a work-around". (Maybe I > implied an answer, but I didn't really state one.) I think the reason > is that too many of us have partial information, and not more complete > information. We know that for us, or a buddy, some specific action > solved a problem (turning off ARTS, adding the network broadcast > address, ...), but too few of us (me included) don't know (and don't > have a good concise reference) to documentation that concisely lists the > 5, 10, 15, or 120 specific requirements that must be fulfilled to get > sound, networking, email, or whatever to work in Linux. So, somebody > knows 1, 3, or 119 of these, and mentions these in an email to somebody, > but, it doesn't work because my problem is that I'm missing the 5th, > 10th, 15th, or 120th requirement. So finding the 5th, 10th, 15th, or > 120th requirement seems to be a work around. (I'm not sure that hit the > nail on the head either. Writing this (I hope), and any comments I get > from others may help clarify my thinking on the subject.) > > So, what am I doing about it? Just ranting? No, or not intentionally > so, see below. > </continuation of rant> > > Like I said, this is a continuation of the rant. I don't have the > answer. I was/am trying to create an answer on my WikiLearn site, but > I'm not sure I have a good example to point to. The best examples are > those that include a ...Beginner and ...Reminder page for each > subject. Here are two examples: (They are not quite what I want yet, > they don't explain what the GUI does, primarily because there is no GUI > involved in these examples.) > > http://twiki.org/cgi-bin/view/Wikilearn/UsingFtpBeginner > http://twiki.org/cgi-bin/view/Wikilearn/UsingFtpReminder > http://twiki.org/cgi-bin/view/Wikilearn/RsynchingALargeFileBeginner > http://twiki.org/cgi-bin/view/Wikilearn/RsynchingALargeFileReminder > > If anybody wants to take the time to look at these pages and offer > (constructive?) criticism, that would be appreciated. If anybody wants > to help make more pages along the same lines (or along better lines), > let me know -- I'd love to have help. (You don't really have to let me > know -- you can simply register at > http://twiki.org/cgi-bin/view/TWiki/TWikiRegistration, and begin > creating or modifying pages.) > > Be aware that WikiLearn is currently in a temporary location -- I want > to move it to its own site on SourceForge -- I have approval for the > project, but could use help in setting it up. See > http://twiki.org/cgi-bin/view/Wikilearn/WikiLearnToDos for the beginning > of a list of tasks that need to be accomplished to move to a separate > SourceForge site. > > I guess another intent is that WikiLearn pages be short and concise (a > little less concise in the beginners version), and deal with related > requirements by hyperlinking to another short concise WikiLearn page (or > a good concise reference outside of WikiLearn (or mirrored on > WikiLearn). For example, note that I now mirror the Filesystem > Hierarchy Standard on WikiLearn. I did this because (1) I couldn't find > a hypertext version on line, and (2) I wanted to have "anchor links" (?) > within it so that I could link from other pages to specific parts of the > FHS. > > See, for example http://twiki.org/cgi-bin/view/Wikilearn/DirEtc (name to > be changed to SlashEtc) and follow the link that starts FHS#3... . > (This is one of a series of pages that define various Linux related > terms in conjunction with my participation in the Basic Linux Training > course by Henry White -- follow the BLT link on that page to learn > more.) Like all wiki pages, these definitions are a work in progress. > I am "rushing" to get something written down to define each term, with > the hope of going back (or having others) improve them later. > > Aside, another thing I'm working on (see > http://twiki.org/cgi-bin/view/Wikilearn/BeginnersManPages) was going to > be adding a simple syntax example to many man pages, but it looks like > the more practical short term approach is to create a new "beginners" > man page with such simple syntax examples for several commands on one > man page (with hopes that later they will be moved to specific man > pages). (This after corresponding with the maintainer of the man pages, > see BeginnersManPagesDiscussion.) Again, this is a wiki page, and help > is welcome. > > Randy Kramer > > ---- > > Want to buy your Pack or Services from MandrakeSoft? > Go to http://www.mandrakestore.com -- Ric Tibbetts Linux registration number: 55684 If you want to help advertise Linux - point your friends to http://counter.li.org/
Want to buy your Pack or Services from MandrakeSoft? Go to http://www.mandrakestore.com
