Brad;
You are right on with the exception of the fact that when a guy/girl gets a
degree in computer science they forget how to speak common, everyday
English. "Never use a common word when a much more arcane one will do".
After all, we must prove to the public that we are college graduates,
mustn't we??
The average guy is my wife. She too is a college graduate, BSN (nursing).
She wants to use the computer for reading email, writing the occasional
letter and surfing the web. She complains and rightly so, that she doesn't
do more with the computer because it's too hard to understand the
documentation. What the hell does n stand for and what is compiling,
compiling what, are questions I get from her. She is happy with Windblows
because all she has to do is point and click.
And that my friends are why Bill Gates is worth $100 billion, he
understands that and the rest of the programmers, sysadmins, etc, etc do
not or will not.
Make it easy and the people will come and give you their money, make it
difficult and they will stay away.
Joe
*********** REPLY SEPARATOR ***********
On 5/20/2003 at 12:36 PM Brad Smith wrote:
>> <rant>
>> This is, imo, the result of a general malaise among developers,
>especially
>> OSS developers, who tend to consider themselves ubercoders only seconds
>> away from being freed from the matrix[tm]. One of the results of this
>> malaise is that documentation has become an afterthought.
>> In the previous proprietary software model(s), coders would reach a
>> feature milestone, then the code would be frozen and docs would be
>> written, then there would be a release. With the fast evolution and
>> distributed nature of open-source development, however, this methodology
>> can only lead to disaster. By the time docs are written or updated
>> following a code freeze, there are already releases or prereleases of a
>> newer software version to which at least part of the new docs no longer
>> apply.
>
>This hits on something that I feel very strongly: The single biggest thing
>keeping Linux from the
>average user's desktop is not pretty GUIs and so forth, though that's a
>big factor, as much as the
>lack of easy to read, easily accesible, consistently written documentation
>and other avenues of
>support, both for the OS and for individual applications (especially the
>latter).
>
>The biggest gap that Linux has to bridge is the learning gap. Microsoft
>has an advantage over
>Linux in that everybody sort of learns their OS by osmosis. Thye're forced
>to sink or swim with it
>every day at home and at work. The fact thay ever since DOS MS has
>generally opted for fewer
>features/flexibility in favor of a simpler user experience (9x in
>particular) also helps.
>Frustration with Windows might prompt someone to buy a $200 WalMart PC and
>a book. But if the
>solution to an application-specific problem is "Oh, just go to
>someproject.sourceforge.net and
>look in the documentation section" or "just do 'man someproject' or if
>they complain that feature
>X isn't in their book and are answered with "Oh, that feature hadn't been
>added to the program
>when your book came out", the average user might not find it worth his/her
>while to go digging
>around through websites and cope with badly written (or simply not written
>for new users) docs in
>order to solve the problem at all. It's what Niel Stephenson called the
>'Blinking 12' phenomenon,
>referring to the ever-blinking '12:00' on the VCRs of people for whom
>getting rid of the annoyance
>was never worth the trouble of deciphering the manual. The way I see it,
>work needs to be made in
>two directions: standardization/interoperability between graphical
>environments, package managers,
>etc (which is a whole other flamefest I won't go into here) and
>documentation. I give a hearty (if
>hypocritical) 'amen' to Levi's statements about making end-usr
>documenation an integral part of
>the development process and add this: Documentation needs to be not just
>present, but centralized,
>standardized and, in many cases, written by users rather than developers.
>
>What if, for the documentation of any application, all you had to do was
>look it up at tldp.org
>(or some other central location.. call it 'docforge.net')? The
>documenation, either linked to or
>housed locally, is provided via a standard interface and follows a
>standard set of documentation
>guidelines like those used for the HOWTOs. Docs could then be downloaded
>as a single package,
>individually or viewed online (again like the HOWTOs). The standards
>wouldn't have to be anything
>particularly draconian, just, for example, to require that technical terms
>be hyperlinked against
>a master glossary (which would be useful in and of itsself). It would take
>about 10 lines of Perl
>to write a script that could automatically cross-reference and hyperlink
>any documentation with
>such a glossary or even a pre-existing database like everything2 or
>wikipedia.
>
>The next obstacle after providing a more usable interface with regard to
>documentation would be
>actually getting it done (and done well). Like Levi said, most coders
>(myself included) would
>rather create than document what they created. I comment my code pretty
>well (a heck of a lot more
>than some I've seen) and with things like javadoc, phpdoc etc, it's
>getting easier and easier to
>create passable docs... for other developers to read. It's the end-user
>docs where Linux can be
>really lacking. This is actually where those same end-users can get
>involved. There are plenty of
>people who are technical enough to use and enjoy open-source software
>without being developers
>themselves. I'm one, working primarily with web languages but obviously
>using a lot of C
>applications. These are the people who should probably be documenting the
>use of programs, NOT the
>developers. Being a good developer does not make you a good writer of
>documentation, even if you
>acknowlege it's importance. Imagine a website, though, where end-users who
>want to contribute to a
>project can work on the documentation in much the same way that developers
>collaborate on the
>code. I know there are projects that do somethig like this now, but not in
>any kind of unified
>format/location that I know of, so hear me out: For each project, there
>would be a TODO:Doc list
>of topics that need to be documented. Interested users could then claim a
>topic, commit to having
>a draft in by date X and then submit a draft for peer review by that date
>(failing to do so would
>make the slot 'open' again). Once posted, each section would have user
>commentary submitted below
>(like the excellent system in place at php.net, though I would add
>threading to allow for
>responses to the responses and so forth). Besides the topic-by-topic
>guides, screenshot-laden,
>'how to use the basic features of this program' tutorials are far too
>uncommon but would make a
>great collaborative effort. With the right interface it would be possible
>to make collaborative
>documentation as engaging a process as collaborative development. This
>would significantly affect
>the learning curve for your average application and thus make Linux
>significantly more accesible.
>
> Another great avenue for collaborative, user-to-user support is IRC.
>irc.freenode.net is already
>doing this, with channels devoted to specific open-source projects, and
>there's a #linuxhelp on
>every irc network in existence. But its existence of app-specific channels
>is often
>under-advertised and many chanels are sparsely populated at best. With a
>java-based irc client, a
>connection to live chat could be a click away from the documentation page.
>The addition of a bot
>to the channel would make it easy for users to be referred directly back
>tot he appropriate
>chapter(s) for common questions.
>
>..on a related note, the sLUG website mentions using IRC in the
>'volunteer' section does the LUG
>have a chan/server anywhere?
>
>There are a number of projects that already do things similar to what I
>describe: sourceforge
>technically facilitates collaborative documentation, as does wiki, but
>neither has a particularly
>friendly interface, IMO. Gnome has built-in irc support for some but not
>all of their products off
>of the help menu, which is a great and innovative first step. Nonetheless,
>I get the sense that
>with more coherance, more universality, more attention to
>user-friendliness and an acknowlegment
>of the importance of documenting individual applications, these could all
>do much more.
>
>But here's the point where I have to shut up because for all my ideas I
>don't have the time to do
>bugger about them right now. =:) But hey, maybe one day.. I am curious to
>see if people think I'm
>even on the right track here, though.
>
>
>--Brad
>
>...Wow, that was SO much longer than I originally intended it to be.
Sorry! =:)
This archive was generated by hypermail 2.1.3 : Fri Aug 01 2014 - 20:06:35 EDT