> <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