Slashdot Mirror
Feature:Thoughts on the Linux Documentation Project
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:
- 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.
- 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.
- 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.
- 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.
- 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
command line switches to generate specific
sections? Doesn't look robust (to new changes) to me,
but I'll consider that idea
(I'm currently working on Docbook-to-man utility)
INFO just seems so prickly to me; I hate having to use it. 'man' is so ubiqitous (can you say de-facto?)
Is there something about 'man' that is somehow non-free? or anti-GNU? Why /did/ GNU come up with INFO?
I wondered that myself for a while. I think it becomes clear if you look at the info pages for a little while. Notice that you have linked sections -- what basically amounts to a hypertext browser. Some info pages are even smart enough to link to info pages for other GNU programs, ultimately creating a "web" of documentation that you can jump around in. I don't think `man' can do that.
If you ask why GNU didn't use html, the answer was it didn't exist way back when in the dark ages of computing. :) `info' pages also provided a method to generate nice printed documentation for those of us who don't always like to read our documentation on the screen.
man pages also had acquired a reputation for being short and rather terse on some topics. I believe GNU wanted to avoid this as well (although I still find myself baffled by the info format sometimes). Quite simply, it was the best available solution they had at the time. Or rather, the best solution they could come up with, since I doubt similar systems were free in those days.
I very very much agree. I have gone to a few HowTo's and found that there has been a sentance that was worded a way that is really bad. After spending a hour learning the program in and out I understand what the author wanted, but I want to know how to submit that simple tiny change. A simple way. Benjamin Meyer
As one of the people on the kde-docbook team, I know first hand how difficult it is to properly assemble the docbook tools so that they work well with the latest DTD's and with the KDE stylesheets.
We're getting close to providing a good distribution of tools, and there has been a new release of the Cygnus rpms that includes DocBook 3.1 and the latest stylesheets so that should help too.
"of excellent quality"? Are we reading the same documents? I have been playing with Linux for 6 months no and I've been a professional programmer for 2 years. I would hardly call myself a "newbie" to computers and IT. I' may, in many ways still be a "newbie" to linux but that won't last long. I really want to learn how my Linux box works (RH5.2 if you must know). My problem is the LDP docs are often out of date and irrelevant. When I was trying to configure my machine I spent days -DAYS not hours - trying to get my X server working properly, trying to get my printer to work and trying to get my modem to dial out to my ISP without being logged in as root or SU -ing. It took three months to do the latter and the problem was only solved when I stumbled across an alsmost unrelated post on Deja informin me that my serial port should be given world read access. Only then did it work. Now don't get me wrong, I like learning...and this whole experience has taught me a lot about Linux. But I learned all of it inspite of the LDP not because of it. The most useful info was on Linuxnewbie.com or on the news groups and certainly not in the HOW TO's. I'm a geek and a programmer and I love this stuff. If its this difficult for me to find out how to do something which on other unnamed OSes are automatic, how do you think the ordiary Joe or Joesephine will feel. They will say Linux is to hard and the "Documentation" doesn't help or work...and they will stick with that other unnamed OS. Is that what we want? Should it really be this difficult and time consuming to learn? The LDP needs to find a way to keep up to date and write better material in a way that's easy to find and understand. How? I wish I knew...staying the way it is will only hurt the Linux movement.
Never by hatred has hatred been appeased, only by kindness - the Buddha
I don't know what HOWTOs you guys are reading, but I've been using the LDP for over a year now and for the most part, it's always been up to date.
And even when a HOWTO hasn't been in sync with "the latest version", it's always been enough to point me in the right direction.
For example, the PPP HOWTO, which hasn't been updated in about 18 months...I was trying to hook up a laptop with a null modem cable. Nowhere else on the net could I find ANY information about connecting 2 Linux boxen via null modem. The PPP HOWTO gave me the proper command to use, but it didn't work. Using that as a base, I read the pppd manpage, and realized that I had to add the 'local' option...Wham! Bam! Thank you, Ma'am! 5 mins later, I was up and running.
Sure, it was out of date, but without it, I'd probably still be fumbling with options...All it required was a the application of a couple ounces of grey matter.
Maybe this isn't simple, and maybe this is a dumb idea ..... please comment.
.... the rest of the thread is deleted and it starts from zero again.
/. story by reading the comments, you could get a truly global idea on some docs.
Take the slashdot code, do one thread per topic (or sub-topic or whatever). people can post all the comments/add ons/ comments on comments etc.
Others can moderate which comments are good or bad.
Then , when there are 100 comments (or more or less) on the thread, someone goes through them and integrates all the 2+ comments into the topic
Would it be possible to automatically integrate the 2+ comments in the thread and delete the rest?
For easy updates the info HAS to be entirely WEB based. All the comments posted by various people would also REALLY help a newcomer to understand what is going on as well (different ways of seeing the same thing).... just like you can get a media-free view of any
And for man pages, you definitely need tkman.
--
lynx 2.6 is unusable on a 486 with a math coprocessor. just too slow. and lynx seems to need ~8 megs to render a really big page.
Info was comfortable on a computer 1/5 the speed and 1/2 the mem.
but, as much as I dig Info, I hafta admit that html can and prob should replace it now that computers are faster.
"the LDP was the original (and is still the only) volunteer-run documentation effort for Linux. As it turns out, it is very difficult to get volunteers to write complete documentation for a system the size of Linux and keep it up-to-date..." Which is why I believe that documentation should be tightly bound with the programming process. Instead of the afterthought it appears to be now. Make a change(conceptual or code), it's automatically docummented. This process will need the assistance of a human to clean up and make clear considering the output is meant for humans. But the burden will be lesser than starting from scratch after the fact.
As an end user, though, I want simple. Ascii is OK, and HTML provides miscelaneous improvements like boldface, bullet point lists, and the often underestimated ability to rewrap the sucker to a different window size without winding up with wasted space or scrollbars, or even printing it out intelligibly on the first try.
Just about anything else is probably getting too fancy. Postscript, PDF, or Tex may provide professional publishing capabilities, but will they provide legible text if I've booted from a rescue disk to a text console on somebody else's system and only have "cat" (or if I'm lucky, "less") to view the file with? I can ignore paragraph tags in that case, but I'd better have that postscript printed out somewhere...
I'm all for keep it simple.
Hopefully soon kword will be avalaible, and in the longer term come standard with all linux distributions.
Would not kword be a more attractive authoring tool than sgml?
I don't think a SGML/DocBook 'frontend' is really
feasible. I mean, what sort of usability
advantages would such a tool create?
DocBook is relatively hard to use because it has a rich set of tags, like ReturnValue,
how are you going to represent that in an text-editor-like or GUI docbook editor?
I think the easiest way is to write a short docbook tutorial which spells out the commonly used elements by usage.
In fact I already have some man pages written in DocBook just for demonstration, I should write more someday.
The problem with this approach is that there wouldn't be any ...
semantic markup in the documentation, and would be disorganized
just like all the READMEs that come with free software.
Not that we should prohibit people from writing this way
The problem, though, is not so much "do good tools exist?" as "are people using the good tools?" or "how do we get people to use our better tools?" etc...
A "good tool", of course, would have to be one which is easy.
The LDP was a valuable source of documentation when everyone was using Slackware in '94. Look at how outdated most of the information is. The Modules-HOWTO, critical information for newbies and wizards, is unmaintained, and hasn't been updated in years. Currently the best source of Linux info is Dejanews.
Matt, it IS true. The LDP info is sparse and out of date. All the statements you make about volunteer projects are true, but isn't it ironic that Linux itself is the same kind of project, and yet its development appears to flourish, even as LDP languishes?
Linux desperately needs good, detailed, and current documentation for users and developers alike. There need to be some commitments authors make before being granted custody of a document. In particular, there needs to be a commitment to currency.
It's true that volunteers cannot be forced, but unless someone who is highly motivated to see LDP succeed takes charge and contacts each of the authors on a semi-regular basis, the project will collapse from apathy. Authors need to feel that they are part of a cohesive gropup, I think.
My own pet peeve is the Serial Programming HOW-TO, which has not received a revision for over 18 months, and was written by someone who admits his understanding of the topic was poor.
Once an author stakes a claim as maintainer for a document, there should be a requirement that the author revisit the document, perhaps quarterly, and do two things: first, review and correct or amend, and second, comment back to whoever is the coordinating member of the group that the quarterly work has been done. If the maintainer fails to maintain, then the document should be returned to the pool of unsupported documents. A web site with a list of ownership and status on the docs should not be too onerous a task for someone to maintain (see the Lazarus site for a model.)
I am new to Linux, but have been writing software for 25 years, on other OSes. I find the state of LDP docs, and of Linux docs in general, very frustrating. I have shelved my plans to move some of my company's development to Linux simply because on Linux I lose the ability to adequately schedule and predict development time. I doubt that I am alone in this.
There seems to be a pervasive assumption that we all studied Unix in college. Sorry to disappoint, but I was a fine arts major, and came to software design after having self-educated on hardware design. Coming to software from a hardware background, I expect a certain rigor and detail which is seldom found in software manuals, at any level.
I look on Linux as a potential alternative to Windows. So far, the stress must be on potential, as I cannot and will not commit the welfare of my employer's products to a system for which answers are often very hard to find.
--- Bill
Your point is valid, to an extent. In my case, the lack of quality information caused me to put Linux aside for now. I'm quite willing to contribute when I have something to offer which is of sufficient quality, but I will not expend energies on producing a document which does not improve on what already exists.
I tried LDP, and I also tried the newsgroups. My need was for good information on serial programming, and the responses I received were few and of little use. The books I investigated did not help, either. The lack of cohesion in the LDP approach, where each doc tries to exist independent of all others was an added hurdle to my understanding.
I'm not interested in point and click answers. I want to see some rigor in documentation. I would like to see documents on low level programming written with an approach similar to that found in the documentation of a UART or a CPU. There is, after all, a high degree of similarity in the topics.
A document which purports to present a topic like serial programming should begin by identifying each of the system functions and structures which is involved, and should clearly define the necessary jargon, within the document. It should make clear, with minimal assumptions about its reader's knowledge, the purpose of structure members, and of function calls. To the degree that it does not, it fails at its purpose. With those standards in mind, review the Serial Programming HOWTO, and see whether is succeeds or fails.
--- Bill
I have to completely disagree here. Much of the good documentation for Linux is written from the perspective of the straight Linux kernel with the standard GNU tools in every distributioon. The primary differences in the distributions are directory structures, packages and GUI tools. With regard to directory structure, this should not get in the way too much if you're willing to explore your filesystem a bit. With regard to packages, for the most part, it's better from a security perspective to download and compile the source for any daemon-level service (sendmail, apache, bind...), which puts you in the same position as someone with foo distro. Finally, on point three, documenting the GUI tools has been left exclusively in the realm of the distro manufacturer's, while the LDP tends to document the standard configuration files, which, IMHP, is the best way to understand UN*X configuration anyway. - Jay Beale jay@math.umd.edu
-Macros and templates for tags that required a lot of other tags to use (such as RevHistories, SegmentedLists, Meta information)
-fill-in forms for complex tags with a lot of attributes with separation of optional and required attributes
-Integration with Jade so I can validate and generate files without having to go to a term window.
-Ability to hide all tags so that people that don't know docbook can still edit docbook files for the purpose of translation or proofreading without having to first convert the docs into another format (which can take a long time if the docs are long!)
-Allowing the user to easily switch/add/modify their DTD and stylesheets without having to fool with catalog files.
I like howtos, they are pretty sweet and generally answer my questions. There are some really good ones, there are also a bunch of lesser howtos which aren't part of the standard cannon and you just sort of stubmle across when looking for something. Some of the bigger ones need to go beyond that though, they already have for the most part.
I also have looked at a number of linux books and a good portion of them are LDP in print or a collection of HOWTOs. Now publishing your own dist has never bothered me because the is definitely some service being provided in getting everything on a CD like that and there is usually some value added in the install. Simply downloading HOWTOs and binding them seems a little cheap though. If you can do that, then they should also be in an online book form as well. One big PDF complete with links and everything. Something that get's compiled regularly, has people in charge of various sections, and acts just like any other living project. Once it looks like a book the issues about formats and whatnot start to go away because you're either contributing to the book or you're just writing a doc. There are some ego issues to work out, two people can't write the same sentence but I think it could help to make it more like a product.
I also think a help database is due. There are reams and reams of questions asked an answers provided on numerous Linux subjects on usenet and various mailing lists. We should start putting that information into an expert system. We should start putting all the linux information on all the different linuxes together into one place. It would be huge but it would be very useful and there are so many tricks and tips and hints that get asked for over and over. It would be great if I could pop that extra CD in that came with my Redhat and ask it questions. Again, this is more "product" oriented, LDP doesn't make products and they need to think of it that way to get the movement and the fluid nature of linux going.
I think they need to have some goals to make things bigger and better and there is still plenty of work to be done in terms of consolidation. Documentation is still one of Linux's weakest areas but there are great HOWTOs and lot's of documentation, it just needs to be cleaned up and they need to shoot for a higher goal.
This is my signature. There are many signatures like it but this one is mine..
> my favorite pages, follow references into other manuals and come back, etc. I much
> prefer info. [disclaimer: Maybe man can do this now. It couldn't when I first
> learned unix in the 80s.].
Well, man still can't do that, but various man page readers can. References look like "foo(7)", bookmark lists are bookmark lists, etc.
Bookmarks is a reader issue, and since the command line man page reader has no state it has no bookmarks. References is a heuristic thing with man pages. While being able to specify references a-la hyperlinks is nicer it can sorta be faked.
Basically both GNOME and KDE have man page readers that have all that functionality.
What I am suggesting (and I'm not volunteering: my Linux experience is inadequate) is that the project will not succeed without oversight. Linux continues to grow because there are core groups which are managed. Communication is a large part of the equation.
Linus makes the final call on kernel changes, and has a small core of trusted managers of subsets of the kernel who funnel things to him. That's a hierarchy, and no group of any size is manageable without hierarchy and delegation.
The organization of LDP production seems altogether too loose. What I propose is that through inaction, a HOWTO becomes unowned, and is available to be taken over by a volunteer whose energy level prompts him to do so.
Now. Tell me how that can be worse than the present situation? All you have done is to nay-say my suggestion, and I see no proposal for improvement in your comment.
Stasis doesn't work. Dynamic systems which are not continuously rebuilt and developed are subject to entropy. And entropy is a great way to lose the growth Linux is currently experiencing.
A lot of Linux growth was supported by *nix-experienced enthusiasts and developers. When you exhaust that group, either the docs have to be a damn sight better than they are, or yo hit a plateau.
--- Bill
With so many distributions, distributions themselves should add to LDP documents if they want clearity. This way, they can update their changing policies, which seems to happen with every new release.
The format of LDP doc distribution should be left to distributions themselves. This should also apply to the way in which these docs are viewed/printed/consumed. Maybe Redhat whats to view LDP docs in RedHelp that can use tex/ps/whatever, Debian in DebHelp that can use man/info/whatever, but LDP should not worry about these things.
LDP should stay in course as Matt outlined, an easy way for people to write Linux docs.
>No, that's BSD-style. Copyright and courtesy require this, not the GNU licenses.
My mistake, I've skimmed soo many licenses without actually reading them completely I guess it's easy to mix them up.
LK
"Hi. This is my friend, Jack Shit, and you don't know him." - Lord Kano
It took three months to do the latter and the problem was only solved when I stumbled across an alsmost unrelated post on Deja informin me that my serial port should be given world read access.
/etc/groups.
----------------------------------------
A better way is to find what group your modem's serial port belongs to and add your username to that group in
'Intellectual Properties' are uncontrollable in the wild. To base an economy on them is just stupid.
I have to agree with Matt here (and in general through this discussion), the LDP may not be the most up-to-date place to get documentation, but it is STILL the first place I look- the orgaization is clear, the info is always what I need, in the format that I need it and in a place that I can find easily.
:)
Many of the HOWTO's have been invaulable to me in getting sub-system X up and running in less than an hour. Yes, some of the Documentation is old, however some of it does not need updating as frequently (the Proxy-ARP-HOWTO for example). The ip-chains HOWTO or video4linux-HOWTO (if there is one) would be something that could use updating a bit more frequently.
The point is if people want documentation that is current and up to date we all have to strive to do that, package maintainers should keep up with the man pages, even for -devel release (I love the Rasterman but sometime E is thin on the documentation..) and people who find old HOWTO's need to contact the maintainers and give suggestions. I my self am trying to re-edit the NIS-HOWTO for organization and clarity, the info is in there, but some times the langauge is funky. If you find something wrong in the kernel and fix it, don't you send the patch off to the module maintainer, Allen or Linus?
Allowing HOWTO's to be viewed as "leased" I think is the right way to go, however it involves all of our work. Think about it: in the time it took me to write this post, I could of edited a paragrapgh of the NIS-HOWTO, make all the world a happier and easier to authenticate place
With the amount of e-mail I receive, it is impossible to reply to everything. Also, I placed my documents under the GPL so that people could work with them without my explicit permission. You should have run with it anyway!
This is false. It is not possible to convert automatically ("mechanically"? sweet God!) from HTML to TeX in a reasonable way, since TeX contains information that is entirely absent in HTML. Ditto HTML to SGML. Ditto HTML to PostScript and vice versa. Ditto plaintext to much of anything.
SGML is the best all-around choice, since it contains more information than any other format. TeX is also quite good. texinfo is not as good, but it will do.
Incidentally, TeX source is quite readable. Your concern in that regard has more to do with the formats provided by the LDP than with the submission formats. If a contributor sends the LDP an SGML document, they can automatically convert it to any number of formats, some printable, others browseable, others viewable through cat or similar programs.
In summary, the choice of a document format is a lot more complicated than you make it out to be, and a lot more relevant as well.
--
Some keywords for the NSA in the Lord of the Rings universe: One Ring bind find Sauron quest Nazgul freedom
Indeed. Matt more-or-less suggests that we changed
SGMLtools from Linuxdoc to Docbook just because
we are a bunch of guys preoccupied with tools, but
in reality Linuxdoc-SGML scaled extremely bad,
with no support for inclusion of HOWTO's into
anthologies, etcetera. Furthermore, authors were
(naturally) pushing the Linuxdoc to its limits,
making predictable conversion harder and harder.
That's why the SGMLtools project moved to DocBook: to make sure that whatever authors provide can be
used to the max, now and in the future. Not because we liked to ditch SGMLtools v1 and start
again from scratch.
The fact that FreeBSD, Gnome, and a host of other
docware-projects are all moving to DocBook proves
our point. Personally, I think it is unfair to
authors to let them submit documentation in suboptimal formats, because their effort will not be used as widely as is possible - to make sure this happens is the responsibility of the LDP managers and the toolsmiths.
Having said that, we badly need more DocBook documentation (although an (open source) book will appear RSN - see www.docbook.org) and boilerplate material. And programmers that make sure that whatever the authors provide, it is rendered in the best quality possible in the most important backend formats (HTML, PDF, ASCII, Info, man and
RTF).
(I'm the author of SGMLtools v2, BTW)
But then there's no guarantee it'll get put on the LDP site, and could well sit rotting on some irrelevant server somewhere. I had to have approval from _someone_.
People who want to write docs want people to read them!
Gerv
I just picked up "Linux Complete" for $19.99 (actually $17.99 at Crown). It's mostly HOW-TOs from the LDP (and it says LDP on the front and back covers) with some commentary thrown in and IT ROCKS!
:-)
This is a really good book. Almost 1000 pages, and the HOW-TOs it chose seem to be really up to date. It really covers networking and security well.
It's even got the GNOME and KDE user manuals (though if you need a manual to use Gnome or KDE then you better stick with Windows) and a Command reference (looks like the man pages).
The only complaint I have is the command reference should have the current command being discussed listed on the header of each page.
I think this is an "official" publication from the LDP. It mentions the LDP alot, and the author says in his acknowledgements "we of the LDP".
Anyway, I just wanted to point out something that I think the LDP is doing RIGHT NOW that is good (this book came out sometime this year)
Online docs are great, but I have this fetish about holding a book in my hands...
-geekd
Maybe someone could write a HOWTO to make things simpler for me. I have several HOWTOs that I've printed, and as I've read them I've edited. Simple things. A misspelling here...reword a sentence for clarity there. Things that have made the text more readable for me.
How do I funnel suggested changes/corrections back to the author with minimal fuss? Shouldn't this be the first HOWTO one should read? Maybe the directions on how to submit changes should be at the top of every howto? Yes the author will be diluged with spelling error notifications for a week or so, but as the corrections are made the notifications will move quickly from 'you misspelled...' to 'the correct syntax for the command is..' or 'a clearer way of saying this is...'
So, make it simple for people (me) to submit editing. And put the directions for doing so on title page of every HOWTO.
Aah, change is good. -- Rafiki
Yeah, but it ain't easy. -- Simba
I have more luck at Deja then the LDP which appears to be quite obsolete information and i would point someone in search of help there far before i suggested the LDP. In theory it is good, but too difficulty to maintain.
I hope people contribute to it. I will... i think.
Every time in the recent past when I've gone to the LDP site(s) it's contained the same bunch of circia-1995 documents. I'd come to think that it was a dead project, and that all the good writers were cashing in on the Linux-Book-Boom. (coming soon to a Barney's Noble near you!)
If it were not for the LDP, I'd never have been able to get up and running with Red Hat 4.2 wayyyyy back when I bought it. Since then I've been able to install and play with several other versionas and distros. Yesterday I picked up Mandrake 6.0 and I owe my linux knowledge and prowess in very large part to the information available through the LDP.
IMO the LDP should be under the complete control of those who created it. You see how Linus is the patriarch of kernel development, that is how the LDP should be run.
Who can be trusted to be loyal to the project more than the one(s) who created it?
I think that a GPL type license for documentation would be a good idea, just perhaps stronger provisions to make sure that the original author of a document gets credit where it's due.
"Said documents can be copied, transmitted, edited, published by anyone provided
1. Original author(s) is (are) given credit for creation of said document.
2. Any changes made to the document are commented, and that reasonable efforts be made to give a copy of the changed document to the original author.
3. No fee be charged, beyond that of the price of the media and packaging, for distributions of the documents.
Just my 2
LK
"Hi. This is my friend, Jack Shit, and you don't know him." - Lord Kano
...just like KDevelop makes a good start for helping write good HTML docs to your programs, there has to be a front end that makes it easy/possible even for a newbie to submit text in SGML/DocBook format. As both Gnome and KDE are going DocBook for their documentation, there's some chance we'll have those tool in the fhe forseeable future.
To this day, I cannot accomplish simple navigation
/did/ GNU come up
through a texinfo file. With 'man', I can scroll
up down pageup pagedown beginning end, its easy.
INFO just seems so prickly to me; I hate having
to use it. 'man' is so ubiqitous (can you say
de-facto?)
Is there something about 'man' that is somehow
non-free? or anti-GNU? Why
with INFO?
Oh, and small note to developers: maintain your
man pages! (OK, maintain your INFO pages too, I
guess). We users ARE reading them!
I have found the LDP docs of _excellent_ quality in cases where I wanted to now a lot about how the system works. Usenet is great if you want to get answers to particular questions, but if you need the whole story then LDP is superb. Since 2.2 it seems that updates have been slower, I think that's exactly the problem which Matt is addressing.
Could it be that with the 'userfriendly' distributions (RedHat, SuSe) nowadays less people are interested in the whole story? That could be another reason for lags in documentation.
But when a user asks me something about Linux, the LDP is the LAST place I'd tell him to go. It's hard to find anything in there. It gives next to no details on anything useful, is outdated in a LOT of places, and in general, needs to be redone from scratch.
:-)
The simple fact is that NO good docs for Linux exist. This is a serious problem that the LDP hasn't been very good at fixing. We need a better way. User contribution is a good idea, if it only worked right. (If any programmers really liked writing docs..
---
- Give a man a fire and he's warm for a day, but set him on fire and he's warm for the rest of his life.
While it's a good thing to cater to the authors of HOWTO documents as much as possible, it's also good to consider the reader's convenience. I wouldn't want to be confronted with a melange of TeX, HTML, PostScript, ASCII and SGML docs in one hierarchy, nor would I care to go searching through multiple hierarchies if the author decided to provide the docs in only one format.
Of course, SGML covers that requirement admirably -- one can generate any number of representations from SGML source -- but unless authors are constrained to provide SGML docs, one of two problems will arise:
These are strictly long-term concerns, however. For now, the LDP has not reached a state of completeness where it can afford to discard any contributions. Please, though -- no MSWord.
--
Some keywords for the NSA in the Lord of the Rings universe: One Ring bind find Sauron quest Nazgul freedom
These are reasonable ideas, but they're not GNU-style.
1. Original author(s) is (are) given credit for creation of said document.
No, that's BSD-style. Copyright and courtesy require this, not the GNU licenses.
2. Any changes made to the document are commented, and that reasonable efforts be made to give a copy of the changed document to the original author.
Again, that's courtesy.
3. No fee be charged, beyond that of the price of the media and packaging, for distributions of the documents.
No, the GNU-style licenses say that you can charge as much as you like, but you must make the source (SGML here) available. For instance, under a GNU GPTL (General Public Text License), O'Reilly or similar could produce a nicely printed copy of the book, but they'd have to say where you can get the SGML to make your own from.
"I want to use software that doesn't suck." - ESR
"All software that isn't free sucks." - RMS
Good one. A well thought out article, with a fair amount of factual backup. I've used the LDP more than a few times and am glad it's there. I'd hate to see it go.v
/anything/ - documentation, a manual, the newspaper. It's too bad, all too often, we forget these things and take everything we read on faith.
I agree with Matt on what seems to be his key concern - that being that beauracracy is often the torpedo to sink the ship. Especially with the LDP, there doesn't seem to be any compelling argument for any kind of authoritative structure to govern it. I've always been a fan of the "something is more than nothing" attitude, and even if 3 in 10 articles contributed are of dubious quality, at least the other 7 are there.
Incidentally, I think I remember some sort of disclaimer on the site saying something to the effect of "we try to make sure contributions are technically correct, but they may not be." This should be something a reader keeps in mind when we read
"Old man yells at systemd"
The original LDP planned to write a small set of long manuals (such as the Linux Network Administrator's Guide or my own Linux Installation and Getting Started). What we found was that Linux moved too fast, and there was too much to cover, to keep these manuals recent. The HOWTO project was a shift towards letting people write short documents on their favorite topic of interest -- somebody might write the Net-HOWTO while somebody else wrote the Serial-Cheese-Grater-HOWTO. This was a fantastic success, judging by the number of HOWTOs and mini-HOWTOs we have now. But this doesn't solve the problem of keeping the material up-to-date.
I don't see any way to force volunteers to maintain documentation; all you can hope for is to get writers who care to maintain their docs and have some incentive to do so. Perhaps there is now a niche market for professional writers and publication companies to step in and help maintain Linux docs, but that's not the scope of the LDP.
The benefits of the LDP are that it's free, vendor-neutral, and anybody can contribute. So, you get what you pay for.
Matt Welsh
I find that the LDP is good when I need an introduction to something new: it seems to have some examples on how to get started, plus a wider over-view (e.g. look at the Linux xDSL HOWTO, a few paragraphs on using DSL under Linux, but lots and lots of info about DSL itself). But after that I need something far more concise: MAN pages. Why aren't these being maintained properly? What is GNU's fascination with crappy INFO. MAN pages are where documentation needs to be focused as these are falling behind, or simply not even being updated as they've been replaced by INFO. MAN is the most useful documentation when you kind of know what you're doing.
I have used LDP many-many times, and love their
existence. I'm not sure about how LDP work, but
to answer problem like tools...
Maybe LDP should allow the author to pick their
favorite tools to write, to encourage productivity...and have volunteer editors, that
edit the document for standard distribution. The editor can do spell checkin, grammar check, and convert it to SGML format. This is another way for people like me who doesn't have enough knowledge to contribute but willing to help.
The reason I never contribute is because I don't feel qualified. Those who are qualified probably don't have time to contribute. Perhaps what is needed is a branch project, or an intermediate step... the "Hacker's LDP" or maybe a new document format... no longer the HOWTO or FAQ, but a new class of "implementor's notes" or something. I guess Mini-Howtos somewhat cover this...
In essence, this would be a centralized version of what people find on deja.com or on people's homepages. If the author wants to compile these notes into the HOWTO, then they can.
It's just an idea. It shouldn't take much to set this up... if somebody has the facilities.
The only issue I can think of is moderation and making sure that the feedback is not redundant... or that redundant feedback is appropriately categorized.
Comments?
Info is hardly userfriendly, but fortunately somebody (Przemek Borys from Poland) made a more usable browser for it: pinfo. It feels more or less like lynx.
1. All LDP documents shipped in their current SGML format.
2. A tool or small set of tools to allow cross-referencing, searching, etc. using some of the intelligence in DocBook.
Basically, use more document management tools to get a bit more out of the SGML that people have worked hard to use.
Should have read :
block of text marked or something would suffice.
And to think I even previewed it....
One possible solution to the complaints about out of date or inaccurate HOW-TOs is to follow the Open Content model. With their Open Publication License, their basic goals are to have book source files open and kept in CVS. It seems like they still have some kinks in the license, but as long as I get my copy of GTK+/GNOME Application Development (Havoc Pennington) which is released under this license, I'll be happy.
David
Is SGML Tools still supported? Wouldn't texinfo be a better choice? Any thoughts?
I believe the class of copyrights should just contain one requirement that the document should be infinitely distributable through the electronic media, and should be available at some internet site. The other requirement that can be forced for a specific class of documents ie books, is that they can only be redistributed verbatim. And of course it is necessary for all documents that distributing modified version without notifying that it is modified, should be prohibited. The legal language will be different, but I think for LDP these three requirements should suffice for all documents. I think what we should definitely allow controlled distribution in other media except electronic. This would allow the author to sell publishing rights to a publisher, and still the document could be electronically free. But this doesn't mean that no hard copies can be taken, there could be a condition imposed that no mass scale publishing can be done without the authors consent. Until we get something which allows the authors to earn their bread, we won't see real good books electronically free. For flamers please understand the difference between plain documents and books. -anand
Love and Linux,
Paul
Certified Black Helicopter Pilot *** Unwitting Dupe of One World Gov'ment
If the LDP wants to be of any use, than IMHO it's required be responsive in the free software (FS) tradition.
/dev/null is the same as killing the project off.
This means there needs to be a clear and easy procedure to contribute and there must be feedback. Having an LDP HOWTO and the therin stated submission address pointing to
I now know of three people (myself included) trying to contribute but never getting any useful reply (I haven't got any btw.).
For my part I only want to contribute a mini-HOWTO because I don't want to maintain SGML code. But trying to publish it (i.e. bureaucracy) has already consumed more time than creating and updating it (i.e. the real work). And it still isn't mentioned anywhere.
It's been in the FS tradition that the passing leader determines the next one. From Matt's posting it seems that there's no such leader currently. How come this happened? If there's no current leader now, why doesn't the previous one pass the leadership on?
*t
PS: The LDP has allways been of very great use to me - thanks a lot for that work!
Ahh, I see. I was using preview.
Weird.
NetBSD isn't a distribution of FreeBSD.
its an entirely different OS and should be treated as such. NetBSD docs don't usually work well with FreeBSD, as they shouldn't, for the same reason they don't work with linux or, better yet, windows documentation doesn't work with linux.
-bugg
no, it's not a completely
different os.
Is based on BSD which is the common
denominator. xBSD might be (IYHO) might
be the best bsd, but bsd's just a really
fragmented free unix.
Old truckers never die, they just get a new peterbilt
Correction, they are siblings.
(i did more research, and most netbsd docs work fine on freebsd btw)
Considering BSD itself is extremely old (in computer years) there is no wonder that it gave birth to different OSes. It wasn't actually fragmented, other works borrowed its code and eventually BSD died.
However much you want to argue, Linux is fragmented. Too many different working distributions. There is just ONE FreeBSD. PERIOD (thats the little dot thing).
-bugg
Thanks.
Great idea. Too bad I didn't think of somthing that obvious.
Actually this was never mentioned in any of the LDP docs either...
The defense rests.
Never by hatred has hatred been appeased, only by kindness - the Buddha
Okay, how, pray tell, do I get faux HTML tags in here? Anyone? ampgtsemiclon / ampltsemicolon doesn't work....
I think the LDP and the man|info take on different tasks. LDP is supposed to cover broader tasks that encompass several different procedures or programs where as a man page is supposed to give you everything you need to know about a single command or a single program.
You were a moderator with 5 points. You should have read the moderator guidelines before you did any moderating
I thought the LDP was dead, but I just took a look and most of the Guides have been updated within the last year or so. The way they were designed(IMHO) they don't need to be up to the minute, that is what the HOWTO's are for. Anybody have a list of where the LDP is lacking? Maybe that should be added to the LDP, kind of a bugtraq for docs.
My only major complaint is the Network Administrator's Guide. While most of it is still good, it is pretty far out of date. It talks about kernal 1.0 and 1.1.14 kernel options. With all the new changes to linux networking now would probably be a good time to update it and add some sections like firewalling and ipchains.
--
?
Documentation is essentially part of software, and the licenses that are good for one are good for the other. If you need to fork the software, you'll need to fork the docs too.
Thus, the Open Source Definition is perfectly good at describing what licenses are acceptable for a free documentation project.
Essays and fiction, by contrast, probably wants rather different licensing. Possibly the McElwaine license: UN-altered reproduction and DISSEMINATION of this IMPORTANT information is ENCOURAGED...
--
Xenu loves you!
With however many distributions, each with their subtle (or sometimes great) differences, to have one document apply to everyone is foolish.
No two linux boxes get from point A to point B the same way.
That is one of the reasons i switched to FreeBSD a couple weeks ago, better documentation (www.freebsd.org, Handbook, excellent man pages, etc.)
and what works for one person will almost always work for you (assuming your talking to someone else who is running your version, and considering stable branch gets new releases only every couple months, thats almost always likely)
$.02
-bugg
Well, why not adopting a copyright that has been especially tailored to such documents: The Open Content Public License?
--
"Just believe everything I tell you, and it will all be very, very simple."
The LDP docs, in the old days of Sunsite and few or no RPM's and debs, were crucial to anyone doing
..., so that I can zoom in on exactly what I want. The more general point here is that finer granularity needs to be intelligent
/usr/doc, and stuff is in html there, umm no its in PDF/PS, or oh, in tex and I need to process it....Now
Linux. Times have changed, and the LDP (IMHO) needs to organize documentation btter I think.
Most People do work in the context of a
distribution these days, and distributions do
things differently. I've often found files at
different places than in the docs. The docs maybe
too detailed for me to spend my time on...I want
to code, not administer my systems, nor compile
everything from scratch. What I am saying is that
the granularity of the docs is not fine enough--I'd be happy to know how to use Linuxconf to set up routing with a small sidebar as to what is going on behind the scenes. I dont want to read
the whole Net-3 howto, unless that is my interest.
Finer Granularity implies better structured documentation, in the sense that it is not enough
to say "section", but section on routing with references to the route giving the error message set
granularity, so that searching is smarter, and natrual language searches are guided.
Now Docbook provides a lot of these tags. You can write API and command man-pages, there are tags like command, syopsis, errormsg, funcsynopsis,
screen, screenshot, input(what the user inputs) etc. Some of these tags are common to all documentation, some ought to be removed, and be put into domain specific XML dtd's, like those involving class framework API's, etc
Docbook is too big to use. A whittled down set of tags, finer grained and more functional than linuxdoc, combined with domain specific XML dtd's
which can then be combined with docbook XML using
namespaces ought to be developed. What would have to be agreed upon, or volunteers found to tag, is
a minimal docbook subset, and a method of combining DTD's. Conforming to these specifications, developers would be free to create their own DTD's, or convertable doc formats, and we would all reap the benefits of structured documentation.
Finally, from a users point of view, there is the documentation finding chaos. Umm lets see
do man bla, is that fails, and even if that succeeds for a FSF software, do info bla, umm we're still not there, wait there is
obviously this chaos will remain as everyone has
their favorite formats. But searching is out of the question, and at the very least, we need a RDF
source(like newhoo) of all the resources on the system which could then be used to display all places where documentation is in the system in something like one of the KDE/GNOME help browser, or
the info browser...
The Inscrutable Gargoyle
Perhaps Linux-related vendors could contribute documentation resources -- writing, editing, organizing -- the way some have pitch in programming talent to open source. Vendor-neutrality could be maintained the same as it has for Apache (being helped by IBM), KDE (Corel) and the Linux kernel itself (the ever-mysterious Transmeta), to name a few.
Freedom's just another word for nothing left Zulus
I'd like to see the LDP contain an archive of all the mailing lists -- similar to geocrawler. A place for short submissions (not whole howtos - something quick and dirty..maybe an article store), a link to all the linux sites which contains docs or an archive of all those sites (like linux.com linuxtune.org linux3d.org etc etc)
The single best thing about the LDP that I've found in the last four years is the one that needs most attention now as things are changing more rapidly. Namely, that one could, with the LDP documents in book form, use the index to find help on stuff very rapidly. With so many new HOWTOs and updates, one would like a new LDP compilation once or twice a year, but few want to put out the cash. It would be very helpful to have access to a good hyperlinked online index into the online docs. But someone needs to do some work to create this index as I've never seen a good one. One would type a keyword or regexp and the tool would construct a page of links, as is typical. But the construction must be based on a hand-crafted database (a full behind-the-scene index) instead of the documents. An extended project could add an option for non-LDP documents. That should be only an option, since such documents often add much clutter since the non-LDP documents would have mixed quality, with lots of duplication, especially of basic info.
So the LPD may not be a panacea, but it isn't all bad either. People deriding it are missing the point - try to improve and make it better.
I still find that the LDP is very useful. Every time I move to something new, especially something that is different in Linux than in other *nix, it is the first place I turn. Some of the HOWTOs I need may be dated, but at least I have a starting point I can rely on!
Do you even know anything about perl? -- AC Replying to Tom Christiansen post.
"Last updated" dates. Placed beside the name of each document in the list. At a glance, you could tell whether a certain HOWTO has any chance at all of being able to solve your 2.2-specific problem.
I went through once and took the last-modded date out of each document and looked through them. Average age of the docs was about a year to a year and a half. An age in Internet time.
They would get updated if it were made easier. I know many people who have busted a gut trying to get stuff submitted, or permission to make "official" changes, but been rebuffed or ignored.
Gerv
Indeed; people should indeed try and get a bit more involved in order to make the whole LDP work. BUT... IMHO the LDP itself should also take a very good look at the way things are going.
For example; earlier this year I dived into INN. I believed it should be possible for an end user to use only INN + a newsreader for all his/her usenet needs. After doing some major reading and trying out I finally managed to do exactly that. No suck, pull, whatever for me; only INN.
I got pretty excited over this since allmost everyone seems to think that its impossible to do this without using external software as Suck. So I decided to see if I could put my experiences into an HOWTO for others to use.
Since I actually do read docs I did as the HOWTO on this subject told me; I wrote an email to linux-howto@metalab.unc.edu telling what I did, how I did it (global) and that I wanted to write an HOWTO. I got no response.
I asked in some (local) usenet groups and on IRC if other people shared these experiences and indeed; the bottom line is that a lot of people thought the LDP staff to be very slow. Some even suggested you should ignore the HOWTO and just mail the stuff.
Because I personally feel just dumping the howto in someones mailbox it is kinda rude I wrote 2 more emails (1 - 2 month period between them) but still got no response what so ever.
At this point my motivation to write howto's has dropped below zero. Perhaps the discovery I did wasn't that special, sure, but IMHO at least someone could have told me so.
First of all, please don't send new HOWTOs or proposals directly to me; this won't help, since I am no longer the LDP maintainer. A good place to discuss this is the Open Source Writer's Group mailing list, found here. It is my understanding that the current LDP leadership is being generally unresponsive to the needs of the community. The OSWG seems to have the community's best interests in mind.
Clearly the LDP needs a maintainer who can allow new people to contribute to HOWTOs which have gone out of date. Maintenance of LDP documents should be considered a lease: if the current owner does not update or maintain the document after a certain time, somebody new should be allowed to step in. I don't think that's happening now, judging from what I've heard.
In response to the people noting that various HOWTOs are out of date: true, but you can't really complain unless you're willing to do something about it yourself. The LDP is a volunteer effort; nobody is being paid to write and maintain these documents. If you're tired of running into out-of-date HOWTOs, do whatever you can to revise the information and send it to the original author, or failing that, to the LDP maintainers. My hope is that the LDP maintainer will allow these kinds of "third-party" updates if it's clear that the current maintainer isn't doing an adequate job.
Matt Welsh
If you find the documentation is out of date, contribute to the project. If you are taking but not giving back, you have no right to complain about the state of the lpd. There is a ton of useful information in there; sure, it won't hold your hand through each little step of whatever it is you're doing, but, hell, it's free. Make your own brain a part of the solution. I'm afraid that developers are getting too used to pointing and clicking their way through every problem.
Because there is no "planned obsolesence" in the
Linux community, documents don't need to change
so much... what was useful to getting a package
up in 1995 is still applicable.
Typically, I find it best to read the LDP document
and then to read the README or INSTALL file that
comes with the latest & greatest version for any
new installation tips.
Mark
I fully agree that the most important thing is to keep things simple. Ofter writing documentation or rewriting a garbled paragraph is done on a whim. Something which allowed the documents to be edited in place when you're reading them would probably increase the contributions, and make the docs easier to read.
For example - using something like amaya to edit an html version in place, or having a system like the php pages, where notes can be submitted via the webpage. All is just one click away.
There are fo course potential abuses of this system, but I'm fairly confident that it wouldn't be too much of a problem.
Rikard
[Science] is one of the very few things that raises human life a little above farce and gives it the grace of tragedy.
I've written a pretty big and complete howto on hwoto setup a bunch of diskless clients and a root-over nfs-server. This howto is available from: http://electron.et.tudelft.nl/~jdegoede/ btw. It is about 2 months old. And I've submitted it about 2 months ago to the LDP hwoto maintainer i got one reaction about there already being an HOWTO (an outdated and very summier one if i might add). The problem is that after that I've kept him sending mails and never got any response. I want to get the howto intpo the LDP but this seems to be impossible since there is no maintainer, and yes it is written in sgml, has the right copyright etc. In the meanwhile I've pointed a few people add the howto who we're having problmes with root-over-nfs and they said: "But i checked the LPD and it wasn't there" And probably a lott of other peolle who I never mett on the net could have used the info too. So imho what the ldp needs most of all is an active maintainer. Regards, Hans