On Tue, 2003-05-20 at 17:41, Joseph wrote:
> 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! =:)
>
But this leads us to one of the major obstacles (IMO) that Linux needs
to overcome. Linux seems to be a secret handshake operating system. It
is what separates Geeks from users, these geeks are happy with this and
do not appear to want John ( or Jayne) Q Public in their for geeks only
club.
>
This archive was generated by hypermail 2.1.3 : Fri Aug 01 2014 - 20:07:42 EDT