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