[LWN Logo]

To: techwriters@hub.org
Subject: Some thoughts on the Linux Documentation Project
From: Matt Welsh <mdw@cs.berkeley.edu>
Date: Tue, 24 Aug 1999 12:09:10 -0700


In the last few months, the Linux Documentation Project has been in a bit
of a rough spot, and it seems that things have not been moving along as
smoothly as they were for the last 5 years. I have seen the latest "LDP 
Proposal" (http://www.linuxports.com/ldp.htm) on the Open Source Writer's 
Group website (http://www.thepuffingroup.com/oswg/), and I have a few 
thoughts on the current state of the LDP and what should be done to fix it. 

As the original co-founder and coordinator of the LDP, I did a lot of
work to make the project a popular source of Linux documentation.
I started the LDP website, moderated the newsgroups, ran the mailing lists,
acted as the liason between LDP writers and CD-ROM vendors and paper 
publishers. So I'd like to share my thoughts about what the LDP needs to get 
back on track. 

In a nutshell, my approach would be minimalistic. I have always found that
when organizing a group of volunteers on the Internet, doing less is always
better than doing more.

Here's what I mean: The LDP is primarily a vehicle for Linux enthusiasts and
developers to share their knowledge about the system with other Linux users.
People are motivated to contribute to the LDP because they know that by
having their docs on the LDP website, and on many CD-ROM disrtibutions, and
even in printed books, that many Linux users are likely to read what they
have written. This is much better than burying the docs on a website somewhere
and relying on a search engine. The LDP is the de facto standard place for
people to go to find out about Linux -- first.

As such, it is *vital* that it is as easy as possible for people to 
contribute to the LDP. Participation in complex standards processes, 
voting organizations, or high-traffic mailing lists should never be a
requirement. Likewise, the tools used to write LDP docs should be easy
to use, widely-available, free, and well-supported. 

Ideally, we should allow people to write LDP docs in any format they 
wish -- but I have found that this makes it quite difficult for the LDP
maintainers to publish the docs in a common format. My compromise was
to always allow people to contribute docs in plain ASCII, but the preferred
tool was Linuxdoc-SGML (now SGML-Tools). SGML-Tools is very easy to use and
automatically generates HTML, ASCII, TeX, DVI, PostScript, and texinfo from
a single source file. Also, it works with any text editor. Any system 
which imposes additional responsibilities on authors makes the barrier
of entry too high, and people will be less likely to contribute.

Another important aspect of the LDP is that it is vendor-neutral and run 
by volunteers. For the LDP to be a mouthpiece of a large (or small) Linux
distributor or other company would defeat its purpose. I am not suggesting
that for The Puffin Group to "take over" the management of the LDP would
be a bad thing -- but it is important to make it clear that the LDP is
open to contribution by anyone, and is not a closed, privately-run 
organization motivated by corporate profit concerns. Otherwise, the LDP loses
its identity as an open organization which exists to serve the Linux community
as a whole. 

My strong conviction is that the LDP exists for only two purposes: First, 
to provide widely-distributed, online publication of Linux documentation 
(through the website, USENET, and other means). This frees authors from 
having to concern themselves with making docs available: they simply send 
the materials to the LDP maintainer and the rest is taken care of. The 
second purpose is to act as liason between authors and organizations 
which wish to publish LDP materials on CD-ROM or in print. It is important 
that LDP authors are represented to publishers in this way -- publishers 
rarely want to deal with authors individually, but would rather deal with 
the LDP "as a whole". 

There are some pitfalls which I think the LDP needs to be careful of
when moving forward:

  1. Too much bureaucracy. Turning the LDP into a complex organization 
     with offices, roles, voting procedures, and standards does nothing
     to further the goal of Linux documentation; all it really does is
     feed the egoes of the people involved. No other successful Linux 
     project requires this level of bueaucratic organization. Keeping things 
     informal makes it easier to move forward and to be flexible in 
     light of change. I have seen too many Linux projects die (or take
     too long to get any useful work done) because of political infighting
     based on organizational procedures rather than meaningful technical
     details.

  2. Changing tools. Unless there is a compelling, immediate, and inevitable
     reason why some new documentation format is required, don't waste your
     time trying to convert all of the docs and educate all of the authors
     about how to use the new tools. Adopting Linuxdoc-SGML was hard enough
     in the beginning; it only happened because it was so easy to use and
     we provided a lot of examples and documentation for the tools themselves.
     I haven't seen any compelling reasons why DocBook (or any other tool)
     will make Linux documentation any better. At the very least, accept
     LDP docs in *both* Linuxdoc-SGML and DocBook indefinitely. Forcing 
     authors to adopt a new tool is the best way to scare people off.
     The LDP isn't about tools; it's about documentation. Don't let the
     tools weenies take over. 

  3. Too much -- or too little -- leadership. Leadership in the LDP is 
     really an oxymoron, because the group doesn't need any real leadership. 
     All it needs is someone to work hard maintaining the documentation 
     archives, running mailing lists, posting to USENET, and working with 
     the various paper and electronic publishers who want to redistribute 
     LDP materials. What it also needs is someone who is communicative, 
     open-minded, and clear-headed enough to direct the group's energy
     towards productive means, rather than endless political discussions.
     What the LDP doesn't mean is a group of people to overlay a complex
     organizational structure over something which is essentially a 
     loose-knit collection of enthusiastic writers. 

  4. Using the wrong copyright. My feeling is that the LDP should adopt a
     *class* a copyright licenses which it will accept for LDP docs, similar
     to the Open Source Definition. This will allow individuals to select 
     their own preferred copyright license for LDP materials, within a 
     certain range of allowable licenses. Forcing authors to adopt a single
     license simply means you will have fewer contributors. Some people
     distrust the GPL, others distrust the BSD license, and still others
     prefer to craft their own. You need to be flexible enough to accept a
     range of copyrights from authors. 

  5. Too much planning. Setting out a roadmap for a collection of documents
     that need to be written is the best way to ensure that nobody will ever
     write them. Writing docs gets done in bits and spurts, and can look like
     a pretty big job if someone draws up a big outline for a mega-tome which
     the LDP plans to work on. The HOWTO project was so successful because
     people could write as much -- or as little -- as they wanted to on a 
     topic of particular interest to them. So what if it's not organized into
     a coherent whole? With the aid of indices and search engines, people will
     eventually find what they're looking for. Also remember that ownership
     of LDP documents is a lease: if someone fails to maintain or update their
     document over time, it's perfectly acceptable for someone else to revise
     it or rewrite it altogether. This happened several times with documents
     that I originally authored.

In short, I think that the only thing the LDP needs to do to get on track
is to retain the essential structure it has had for the last five years. 
Making things any more complicated will only raise the barrier of entry to
new authors, which will eventually cause the project to die out. The LDP
worked so well because it took almost no effort for someone to contribute:
all they had to do was e-mail me the source for a new HOWTO. As soon as you
become embroiled in discussions about new tools and bureaucracies, the LDP
stops getting useful work done and starts becoming "yet another overburdened
Linux project". My advice is to keep it simple. 

I appreciate any comments.

Thanks,

Matt Welsh, mdw@cs.berkeley.edu