> 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.
This is definitely the case - users tend to be much better manual-writers
than developers, with the caveat that most users only tend to use and know
of a small to medium subset of any application's available features.
However, the collaboration of several users should tend to provide fairly
complete feature coverage.
> 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).
Hmm, I have mixed feelings about this. It would be nice to look up, say,
the mplayer howto at tldp.org or docforge.net, but something like that
might tend to be a pain to the developers. Sourceforge.net already has
the infrastructure to allow developers to house docs and allow them to be
community-developed, but few take advantage of that.
> 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.
Standards might be helpful, but it could be difficult to develop a set of
standards to apply to docs for all situations. Additionally, developers
and users might be intimidated by the standards and be more reluctant to
contribute.
> 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.
It should be the developers' responsibility to create and maintain at
least a core of user documentation, even though the users may submit many
changes afterward. The main reason for this is that the devs have a
thorough knowledge of features (and known bugs), and will be the first to
know when a feature or bugfix is added and what impact the addition will
have upon the users.
> 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.
Not a bad idea.
> ..on a related note, the sLUG website mentions using IRC in the
> 'volunteer' section does the LUG
> have a chan/server anywhere?
There's a channel on irc.freenode.net, but it's fairly deserted.
> 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.
Actually, I find the sourceforge interface to be great - click patches,
type in a description, attach a file, and click submit - as easy as
sending an email!
Levi
This archive was generated by hypermail 2.1.3 : Fri Aug 01 2014 - 20:08:13 EDT