GrokDoc Goes Live; All GNU/Linux Newbies Welcome

An anonymous reader writes "Writing at LinuxWorld, Groklaw's PJ asks "What Do Newbies Need to Make the Switch to GNU/Linux? and invites the world - literally - to help with answering the question, by participating in the wiki she and some colleagues have just launched. GrokDoc aims to turn the usual process on its head: "Instead of experts telling newbies how to do things, we will let newbies show and tell us what they need." Might be a fantastic way to help push Linux still further toward that fabled tipping-point."

Comments

Online docs are a good thing...

[mahdi13]

but you know the newbies STILL won't RTFM

Re:Online docs are a good thing...

[Anonymous Coward]

Maybe the problem is newbies not knowing what RTFM means when you tell them to RTFM?

Re:Online docs are a good thing...

[Len Budney]

but you know the newbies STILL won't RTFM

Is that the issue? I didn't read the article...

Montessori Linux

[nightsweat]

This is the Montessori method of teaching Linux. Brilliant. Maybe I can get some questions I've had answered, finally.

SSDD

[Anonymous Coward]

Isn't this just like a regular forum like

www.linuxquestions.org
or
www.mandrakeusers.or g
or
whatever fedora people use?

Its just a fancy forum! Move along, nothing to see here people.

Re:SSDD

[bradkittenbrink]

you must be new here, PJ did it, so of course it's important!!!

Re:SSDD

[Anonymous Coward]

whatever fedora people use?

We tend to rely on the power of prayer.

Listening to Newbies

[wambaugh]

On the other hand, rather than pushing linux past a "tipping point," listening to newbies might lead to many of the aspects of the Microsoft/Mac models that many hard core PC users hate.

Not that I think this is a bad thing, but it's worth considering that if, for instance, standardarized application appearance/performance becomes more important, much of the speed and robustness of Linux may fall by the wayside.

Re:Listening to Newbies

[John Hurliman]

I'm not pointing out the obvious to troll, but remember Linux is just a kernel. If one desktop team decides to make an Apple clone that sacrifices top performance for a common user interface (I don't see how that argument makes any sense at all, but I'll go with it), another team will step up to give you the bare bones written in optimized C and assembly. People have this vision of every Linux enthusiast on the planet except for themselves heading in one unified direction that isn't to their liking; I don't think you'll see that happen any time soon.

Re:Listening to Newbies

[Moraelin]

It's worth pointing out though, that being user-friendly didn't stop Windows from actually being faster than X in a lot of tasks. E.g., repainting a Window works orders of magnitude faster under Windows, while in XFree86 you end up needing such silly tricks as processing only each n'th repaint when the user is resizing a window. Doubly so when the Linux equivalent reinvents the bloated wheel, e.g., by insisting to do its very own font rendering and themed widgets.

E.g., MS Visual C still optimizes a LOT better than GCC.

I know it will sound like blasphemy to a lot of the /. crowd, but MS really isn't a company of idiots who are just drooling over the prospect of coloured buttons. It's what you get when you cross (in more than one way;) a whole lot of hackers, with a whole lot of hard working usability experts.

Most of Microsofts's faults, such as never thinking twice about ignoring the standards if it can optimize better without them, or inventing its own formats, are the exact same things we admire in the archetipal idea of a hacker. (The one illustrated in the Jargon file, for example.)

And indeed it has committed more sins in the name of speed, than for all other reasons combined. (Anti-competitive behaviour included.) E.g., that's the reason why MSVC++ was always slightly deviating from the ANSI standard: they could optimize code better that way. E.g., that's the reason it let drivers run in kernel mode, and made Windows inherently unstable. E.g., deliberately pissing off Sun aside, all the changes they did to their implementation of Java were precisely aimed at making it very very fast. Etc.

So either way, what I'm trying to say is: "user-friendly" doesn't _have_ to mean "slower than a snail". Windows has managed to stay pretty fast (fast enough to play real time 3D games, for example) even while cattering to the newbies. I'm sure Linux will, too.

Now stability, that's another thing. No idea there, and indeed MS doesn't exactly come to mind as a good example there ;)

Plus, as was already said, it's not like anyone will stop you from running another desktop environment, if the newbie-inspired one gets too user-friendly for your taste. E.g., most distros ship with KDE, which is aimed at precisely that: looking like Windows to newbies, yet I happily run XFce 4 instead. A couple of co-workers run Ratpoison, and that's as far from Windows (or user friendly) as you can get in a graphics mode.

Soundcard / Printer Support

[John Hurliman]

Being able to detect and have control panels for common peripherals like sound cards and printers. Some distributions do this better than others, but a newbie shouldn't have to deal with the nuances of OSS vs. ALSA vs. JACK or CUPS vs. LPR just to listen to music and print a document.

So are you saying...

[Mz6]

... that the entire /. community is a bunch of newbies?

Re:So are you saying...

[admdrew]

Though you deserve kudos for actually using that software (and I agree with you wholeheartedly with regards to hypocritical Windows users), your anti-anything-linux rant is amusing and rather silly.

I run Windows XP Pro at home because I play games. However, I've run Red Hat 6.1, 7.1, and 8 on other machines, but have never found them to be terribly useful for personal uses. If I were to constantly have more than one machine, I would probably run Linux as well. I, however, do not have any qualms about running WinXP, especially because it *can* be a very stable and powerful OS.

Professionally, I've done my web developing in the past with perl on a Linux server. As the years went on, however, our company made the jump to Windows 2003 Server and .NET using C#. Though I am no fan of the "corporate bastard" that is Microsoft, production costs have lowered and development has become much more efficient since we made the switch. All biases aside, I have been relatively content to use a Microsoft product in this situation.

Free software is great, but is seldom intuitive enough for the masses. Linux, and the realm that surrounds it, is largely for those that enjoy and have the time to endlessly tweak their software. I have enormous respect for those kind of people, and I must admit that I've felt jealous of them and their coolness.

When you call everyone "IE-using scumsuckers" and "shitbags", you're as annoying as the very n00bs you taunt. At least Linux wannabes are open to software that they don't even use.

Simple

[mrjimorg]

NEVER tell me to modify the xyz file in the abc directory!

Re:Simple

[johannesg]

There is a distinct overuse of the 'advanced' button in GUI's these days. You click to open a config window, and immediately click again to see _all_ the options because some asshat decided that you should initially see only three instead of all four.

Slightly better GUI design for config windows would help a great deal. What we need:

- make the damn windows resizable already! Especially if you want to put in a three-line selection box with 3000+ items! (this is of course a point mostly aimed at Windows).

- Do NOT use tabs, *especially* if you need more than one row of them. Instead, use a Mozilla-style category list on the left side of the window. That allows you to group together related 'tabs', and use longer (and more descriptive) names.

- Group options together in a logical fashion. Disable controls that are made irrelevant by other choices.

- Provide a fscking help option for EVERYTHING, describing the finer nuances of setting or unsetting that option. Don't write "LPGR: sets the LPGR option". Describe what it is, why I want it, what happens if I set it and what happens if I do not set it. If a value is a string, provide examples and full BNF syntax.

- Do NOT use acronyms or abbreviations unless you are REALLY certain they are common words. And even then it is probably better not to.

- Never invert the meaning of a checkbox. Checkboxes ENABLE things. If you check them something should be turned ON, not OFF. "Disable debugging" is incorrect. "Enable debugging" (with inverted state) is. If you do it right you will find you can drop the "enable" without losing meaning.

- While I'm on the subject anyway, checkboxes are for on/off choices. There are plenty of things that masquerade like on/off choices but really aren't (for example, the choice between 22KHz and 44KHz sound has only two options but a checkbox is utterly inappropriate since 22KHz is not the logical opposite of 44KHz even if your application only has those two options). Use radiobuttons or a combobox for those, even if there are only two options.

- Do not hide options behind three layers of windows, tabs, subwindows, and more tabs. You are allowed one layer only. It is provided by the navigation choices in the left-hand column. This allows any user to navigate to his option of choice in ONE click.

- Remember the last location of the user. Select it for him, next time he opens the configuration window. This will probably save another click.

And most importantly, there is this:

- Work with your own software. Try to _feel_ what is annoying; what works, and what doesn't. If some task is unpleasant to accomplish, redesign the GUI so it is no longer a problem.

Blind

[codejester]

Blind leading the blind? I don't see many schools asking students to lead class and I think there is a reason...

Re:Blind

[jamesots]

Blind leading the blind? I don't see many schools asking students to lead class and I think there is a reason...

However, you will see plenty of student teachers observing classes so they can learn to teach better.

Re:Blind

[tsg]

Blind leading the blind? I don't see many schools asking students to lead class and I think there is a reason...

If you're building something for the blind to use (software, sidewalks, whatever), don't you think you ought to ask the blind what they need?

What newbies need...

[Anonymous Coward]

1. An installation process as straightforward and simple as Windows
2. The device compatibility offered by Windows
3. The level of cooperation shared by Windows applications
4. The games available on Windows
5. The simplicity of changing system configurations offered by Windows

I wonder where the heck I can find an OS that does all that and more? Hmmm...

(This is not a bash on Linux. I use Linux and love Linux for doing SERIOUS WORK. Most of the world does not do SERIOUS WORK at home. Windows meets virtually every requirement a home user could have. To meet these requirements, Linux would have to effectively become Windows. I, personally, would never use that distro.)

Re:What newbies need...

[deadmongrel]

1. An installation process as straightforward and simple as Windows
True. Simple installation yes. Like windows no. Why? I haven't come across a newbie who can do a clean installation with windows(I am not including those recovery disks that just dump an image into hdd). No one complains about windows because not many newbies install windows. it comes pre-installed on their system. In linux I really like the 4-click install of XandrOS.Its clean and simple and asks minimal questions.
2. The device compatibility offered by Windows
this is going to a problem because not all hardware manufacturers want to openup their drivers. A lot of them have given out binary only drivers(Think Nvidia) but the drivers suck.
3. The level of cooperation shared by Windows applications
agree.
4. The games available on Windows
chicken and egg problem 5. The simplicity of changing system configurations offered by Windows
I find apple give more simplicity when it comes to changing systems. But if we narrow our vision to what both apple and MS does for usability, then we are bound to make the same mistakes. There are other designs that are much more usable than windows and apple for that matter. We just shouldn't follow windows, just because people are used to it.

I like this idea

[dumpsterKEEPER]

Assuming this is implemented well, I could see this being a very useful tool for new linux users. It seems like the hardest time I have convincing people to at least give Linux a try is when they want to know where to go when they need help. It is often a little difficult to describe to them how they need to search Google, picking through endless messageboard postings and offtopic comments, and find what they need, especially when they aren't even sure what they were looking for in the first place. A centralized resource that is helpful and friendly could be very useful for those who are intimidated by learning a new OS.

Sounds Like a Plan

[fiftyvolts]

This kind of testing is exactly what needs to be done. Recently I took several seminars on useability engineering and useability testing, and I was amazed at how much better you can make a product after testing it. I suggest that if you do plan to add your input to the project that you incoiurage the user to think out loud and write down all the things they say. It's really enlightening to hear a user say something like, "I'm looking for a button to do XYZ." when you know that the feature he wants is in a menu right in front of him.

My only concern is that, quite frankly, I find that the first and most difficult hurdle for new users is installing linux. Many people have no clue what's inside of their machine, and more times than not you need to specify some odd bit of hardware during the setup process.

Heh, I should try this on my mother.

How about this?

[kensai]

Stop calling them newbies. It's to much of a deragatory name and tends to push people away. How about calling them beginners or something like that?

I Disagree

[Seek_1]

I don't consider myself a newbie by any stretch of the imagination, but the majority of the time I still can't make sense out of linux documentation.

I tried every night for two straight weeks (reading the docs, getting some great help from the standard linux forums, reading every samba tutorial I could find etc) to get Samba working on my home network before finally giving up on it (and hence linux altogether).

You can't really complain about newbies not reading the manual when the manual either just plain doesn't contain the information you need, or has wrong or out-of-date information in it.

Re:I Disagree

[Elecore]

I've gone through a few different distros the past year, and I must say that so far, the Gentoo handbook is the best manual for linux I've ever read. They show you exactly what to type, and where, as well as telling you WHY you're typing it. I learned a lot about linux simply by installing and troubleshooting Gentoo.

Re:I Disagree

[KrispyKringle]

It really depends on what you're doing. For something as mature as Samba, you should be able to get docs (and in fact you can--I know, because I've read and used them). But for some new software, the code is beta or done, but the docs have to wait. A good example of this is the 2.6 IPSec implementation. I tried to use it with ipsec-tools and easily got transport mode working, but found virtually no documentation on tunnel mode. I ultimately gave up and went with FreeBSD.

Point is, most commercial software isn't released if it's not documented (not always the case, of course). But Open Source you get when you get it. If it's not done, it's not done but you can still download it. If it's done but the docs aren't, nobody holds the release up. C'est la vie.

Re:I Disagree

[Seek_1]

Really? Well hey, if you can point me to one that'll work with both WinXP and Win2k you're more than welcome to. (Infact I'd appreciate it!)

However, until then, my network server will remain a Windows 2000 machine, where I can actually access its files without any issues whatsoever from other machines.

Re:I Disagree

[Welsh Dwarf]

When a so called 'newbie' starts out he shouldn't (need to) read documentation telling him how to use vi to edit /etc/samba/smb.conf.

Instead he should be directed to a convenient administration tool (swat/webmin) which would allow him to set up his home server without 3 hours spent trying to make head or tail of his new (GNU/)Linux system.

Later, if he wants to become more proficient, or fine tune his installation (in general), then by all means show him the CLI and point him in the direction of a M for him to RT, just not straight away.

What a lot of us seem to forget all to easily is that there is something called information overload, and learning the command prompt/SysVinit runlevels/Samba configuration/hosts.Allow/Deny.... all at once is an easy way to get there. We didn't learn all of this in one weekend, so we shouldn't expect others to.

Re:I Disagree

[koniosis]

This is the attitude that causes so many problems for new users to Linux. People assume that the exsisting documentation and HOWTOs are fine because they understand them and can set up the thing in question without a problem. You are not listening to a REAL user who has REAL problems. This is the aim of this project, to get away from the notion that just because some document already explains it, that is enough. It's called User Testing, and it is something that more Linux projects need to do.

Re:I Disagree

[JohnTheFisherman]

I think I finally got a config file working, and it was a tremendous pain in the ass. I've been using Linux for years, though I usually mostly stick with Windows for some strange reason. Oh....like for Samba. It's very difficult to read through a variety of articles, with 400 different ways to do it, some several years old, all of them conflicting, and virtually none of them well explained. I'm sure it gets old answering newbie questions, and believe me, it comes through in most any answer how tired the 'expert' is.

Even when I set up the share, which finally worked pretty well in Windows, I still can't use it correctly while mounting it in another Linux box. I suppose I still might have something misconfigured, but it keeps telling me the owner is '502,' which is the ID# (user #? whatever you call it) of the actual owner, but not the name of the owner. It sorta works, but not for subdirectories where I still lose ownership of what is supposed to be a full control subdir and files. It's just too much hassle, and I think somethings broken based on how it identifies the owner and permissions. Back to Windows. Hey, everything works. *shrug*

Re:I Disagree

[kfg]

It really depends on what you're doing. For something as mature as Samba, you should be able to get docs. . .

He didn't say he couldn't find docs. He explictly said he found lots of docs.

Finding docs is worthless if they all suck.

In my early Linux days I floundered around for a couple weeks just trying to find basic information. I'm no command line novice either, going back to the days when we typed it, on a typewriter. Finally a simple diagram of the generic file system printed in Linux Journal (that's right, even Linux for Dummies didn't bother to even show me a diagram of the file system, and this is enough editions back that it was still command line centric) and a copy of Kernighan and Pike had me whizzing along in about half an hour.

Because Kernighan and Pike writing generically decades ago wrote better Linux documentation than what was available for Linux, and even better Red Hat documentation than that which came with my boxed set with triple the page count. I would have been better off if Red Hat had just tossed me a copy of TUPE with a note on saying,"Best we can do, you'll have to figure the rest out by yourself."

Because Kernighan and Pike know how to write documentation.

KFG

Re:I Disagree

[RAMMS EIN]

I agree with that. At the time I installed Gentoo, a lot of UNIX commands were still abracadabra to me. Still, I managed to get Gentoo up and running without a hitch, and learned a lot in the process. What this means is that Gentoo, typically considered for advanced users, is a good way to kickstart newbies.

I really think that, in general, one of the best ways to learn about computers (any part of hardware and software) is by diving into it at the deepest level with a good walktrough. This not only teaches you how to do things, but also why you do them that way. With strong knowledge of the low level, it is easy to come up with any solution for the high level.

Of course, the _quickest_ way to learn how to use a computer is to learn just the things you need to use. However, do not confuse this with the easiest way. For example, there is a widespread belief that GUIs are more intuitive, and therefore easier to use than the command line. I disagree. I can hardly think of anything more intuitive than pressing the key which has the character that you want on the screen. From there on, you build up the complexity until you have a command that does what you want done, and press the key that causes the command to be executed.

In a GUI, one typically moves the mouse (in a different plane!), to the location where an action is to be performed, then does one of clicking, right clicking, holding a key and clicking, double clicking, etc. Often, the command to be performed is selected from a menu, which sometimes appears in a completely different location from where the action is performed. Intuitive?

The strength of GUIs is that they are discoverable. Once you learn how to move the mouse, select items, and navigate menus, you can discover pretty much everything a program can do by doing just that. There is a lesson here for CLI designers: make your interfaces discoverable. Tell the user how to get a list of commands and how to find out what they do.

Re:I Disagree

[mrroach]

OK, I call shenanigans on all of you. You're putting me on, right?

You did not even read this documentation that you are claiming is no good.

You also did not look for it very hard.

Let's see...

• go to samba.org
  
• click on USA
  
• click on documentation
  
• choose the html version of the howto guide (the first link on that page)
  
• skim through the index and see "2. Fast Start: Cure for Impatience" and click it
  
• Lo and behold, the two configurations you just mentioned are configurations #1 and #2 on that page.
  

Now, have a look at that documentation, then come back and tell me that it sucks and why, or tell me that it doesn't but that you just couldn't find it, or tell me that you were really just not looking that hard.

-Mark

Newbies don't need Linux...

[Anonymous Coward]

The same way they don't need DOS. And they definitely don't need "GNU/Linux". Give us a break, any newbie who wants to go around pronouncing that awful name all day is a nerdy geek and no newbie.

Anyway, Linux is the underlying OS and no use to any newbie. Newbies want to use a user-friendly desktop system. The discussion can't be centered on Linux itself. There should be discussions specific to each distro or window-manager.

Newbies don't give a shit about the OS. They want to install a desktop and run things and go back and easily find and use the files they created last week. Oh and, no childish games about names, evil monopolies, litigious bastards and whatnot. In other words, no "grokxxx"!

Re:More fluff ahead

[Unnngh!]

A talking, pop-up tux that spits out hundred-page man pages might be kinda funny though...

Re:WM?

[stevey]

You can do far worse than pointing people at The Linux Cookbook.

This is something that is task orientated which seems to make lots of newcomers to Linux (but not computers)

let homer design linux

[happyfrogcow]

ever see the Simpsons where Homer designs a car? that's how Linux would end up if we let the newbies do it all.

What newbies want.

[ObsessiveMathsFreak]

No more command line.

What's That! Blasphemy!! BaSH him to Death!!!

Seriously, I challenge someone out there to make a distro where a user need never resort to the command line interface or a terminal of any kind.

I guess something like....Windows really...

If you ask Aunt Tillie to type
rpm -ivvf lovelyrpm-withnoguitoinstall-2.3-5.rpm

she will, legitimatly I think, return to windows. She's a busy person with no time to appreciate the finer points of red hat package management.(Or why up2date keeps crashing)

P.S.
This does not say that you must get rid of the command line altogether mind. Even XP still has the command prompt, hidden away somewhere.

Resolution

[hartba]

That's 50% of the reason I won't use Linux on my desktop. If I install it, I get one of two scenarios. 1- The screen res is at 640x480 and looks like crap 2- The screen res is at 1600x1200 and I can't read a single piece of text. When I try to change the resolution I either get the screen scrolling around on the monitor or I get a small square in the middle of the monitor. I've used Suse, Mandrake, Knoppix and Red Hat with varying degrees of success but my main complaint is that I don't have a drop down box that will let me adjust screen res, like I can in Windows. At least it's not as functional as the one in Windows. The other thing is Samba configuration. I may be crazy but file sharing on a Windows network should've been the EASIEST thing to configure in Linux. It's the only way that Linux will ever compete in the desktop market. I've been a computer tech for years and have used everything from the TI99/4a, a 286 running a proprietary OS called "8n1" over DOS, to my latest Windows XP machine. I dictate what my family uses as their OS (because I work on their computers for free) and if I can't configure it like they want it, how are they ever going to be able to do it? After working all day long, I don't have time to weed through hundreds of man pages, only to find out there are 10 apps that do what I need it to do, but none of them will do it without editing several files and recompiling. Also there needs to be a big red button in the center of the Linux screen that says - "I really screwed up bad, please set everything back to install defaults"

Avoid Supply Side Arrogance

[4of12]

we will let newbies show and tell us what they need.

This is an excellent idea.

A lot of people in IT have a lot of experience with Microsoft, whose approach since they gained market dominance has been to more or less shove new products to their audience after some token sampling of the marketplace.

But FOSS is currently making a similar supply-side mistake, too: people that want to use Linux to do something in particular for their business have to "just accept" a distro and what's out there. Before you say "but they can write their own app", think - How many small business owners are capable of "writing their own app", modifying an Apache module, etc?

Sure, there's tons of free and open source software out there that people can use to build systems for their businesses, but many of those small business owners have little time or little expertise about how those pieces could be put together to help them. They need help with insight. Call it marketing, for lack of a better term.

Instead of just offering a supply, either as MS offers OurOneSizeFitsAll - take it or leave it; Linux offers an OceanOfFreePartsAnyExpertCanUse, drive a focus more onto customer demand that will help provide more people with Linux solutions that can really help them. And, if it helps them, it will help even more people as they can more easily see how it can be done.

You forgot...

[gillbates]

Anti-virus software and monthly security updates and bug patches.

The typical Windows user has become so adjusted to the idea of constant crashes, security holes, and bug fixes that they'll think Linux is somehow lacking if it doesn't provide them - constantly. After all, viruses are a normal part of computer operation, right?

And should you try to convince them otherwise, they won't believe you. I've actually heard pro-Windows CS students say, "Well, it's impossible for a computer system not to crash from time to time..."

Sometimes I think that Windows is Bill Gates' revenge against all those kids who used to make fun of him on the playground. He charges Joe "corporate-fool" Sixpack exorbitant amounts of money for the software equivalent of a Pinto - sweet revenge indeed!

Re:First step

[c0rN_g0aT]

"I know RMS has a point that many GNU utilities are in Linux."

Linux is just a kernel. Linux is in a GNU system and not the other way around. Stallman is the father of open source software and newbies should be taught this as well as just exactly what linux is. This will avoid stupid questions like "I downloaded Linux and its nothing but a 30 meg source archive for a kernel or something" If GNU/Linux is too hard for them to understand, they have no hope of ever using and maintaining a GNU/Linux system.

Knoppix can be as usable as Windows

[WarmBoota]

Recently, when my hard drive borked, I had to resort to using Knoppix to check my email, et cetera while waiting for the spare time to get things working again.

With a Knoppix CD, I could:

• instantly boot into Linux (look Ma, no install!)
• Access my USB Memory stick
• Create a word processing document
• Print to an HP Inkjet (the configuration was actually less painful than the Windows procedure which dumped hundreds of megs of junk on my hard drive)
• Access web-based email with Mozilla

Now this was incredibly usable to me since I am familiar with Linux in the first place. There are only a few places where things fall apart.

1. Knoppix can be installed to the hard drive, but typing "knoppix-install-hd" at a root prompt isn't the most discoverable interface.
2. I know that k3b burns CDs and Mozilla is used for the Web. Until Linux applications have brand-name recognition of things like QuarkExpress or Excel, I think that application names need to be more descriptive, or some other mechanism is required for users to discover the application purpose. KDE is pretty good with sorting applications into Internet and Graphics folders, but it could be done better. I wouldn't find a hand-holding introduction useful, but others might.
3. I was able to use konqueror to browse a Windows network, but again, this is only because I knew that I could type smb://ipadress/share.

I think that the Harmony Remote concept would be useful for Linux Configuration. For those too lazy to Google for it, the concept is this:

1. Answer some questions on the devices that you actually have (e.g. Do you have a TV, Stereo Recevier, DVD Player, etc).
2. Identify the model numbers (I know that this is a stretch for basic users, but bear with me).
3. Answer some questions about how you want things to work. (e.g. Do you control the DVD volume with the TV or with the Receiver).
4. Once that's complete, activities appropriate for each device are created. The Linux equivalent would be a walktrhough tailored to their machine (Printing, Scanning, Internet, Local Network, etc).

Programmers are poor writers.

[Spencerian]

I'm a computer tech and consultant that generally putters with programming. I wasn't too shocked to see, as I moved to Mac OS X, how badly the man help and documentation files were written.

My career involves many publishing venues, including a very popular book publisher and a city newspaper. While most developers are very adept at their work, self-expression or documentation is not their strong suit in general. The text is jargon-rich and circular, presuming that the reader already has a knowledge base equal to that of the writer.

This one point alone is why Linux and almost all other UNIX blends and clones never get the attention they seek. It's not that the OS is rotten (far from it), but because users have NO FRICKIN' CLUE what to do with it, including installing the OS (which programmers should really assume will be atop or supplementing Windows), and the help information is incomprehensible, if it exists at all.

Further, the diversity of X Window-based interfaces (window managers and desktop managers like KDE) are too diverse, leaving users very confused where anything is. Mac OS X is essentially the only UNIX clone/blend that a grandma can use. Sure, grandma CAN use Linux, but who's going to teach her how in a way that is understandable? She certainly won't try to READ how.

My humble opinion is that programmers should stop trying to steal the likenesses of Microsoft Windows and Mac OS X and attempt to kidnap the companies' marketing and human interface staff!

Re:Programmers are poor writers.

[cluckshot]

I will second the motion on MAN pages being stinking rotten messes. I have tried for years to read them and tried to make any useful sense of them. The problem is that they give you a command name and a set of switches and input values not considering that many combinations have no real value or simply don't work together.

I could use a man page with a few examples for how to use the command. Try chmod for example. Goof around with chmod in a recursive fashion and you are likely to have the OS fail to work! It is easy to not know that unless a program is not editable it will fail to work.

Take the wonderful commands for applications of grep!!! Which goes with which and which conflicts with which and why.

Well if you are not confused you have not tried these wonderful tools. They are powerful but obscure. A MAN page which actually gave you a useful script like command [Switches] [FileName] and actually showed you a simple examle or two might help. tar for example can be pretty awful without a good example.

I suppose a wrapper tool might be in order as well