Feature:Thoughts on the Linux Documentation Project 97
Thoughts on the Linux Documentation Project
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" on the Open Source Writer's Group website, 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:
- 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
Re:Right On, MAN! (Score:1)
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.
Re:Easy-to-use SGML tools needed... (Score:1)
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.
Re:contribute already (Score:1)
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.
not so simple but ....... (Score:1)
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
INFO -> use pinfo or tkinfo (Score:1)
And for man pages, you definitely need tkman [berkeley.edu].
--
Info was right in the 1980s. (Score:1)
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.
Re:Authorial Convenience vs. Reader Convenience (Score:1)
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.
Re:not so simple but ....... (Score:1)
LDP quality impedes further Linux growth (Score:2)
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.
Re:contribute already (Score:1)
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.
Features of a good DocBook editor (Score:1)
-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.
No ambition (Score:1)
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.
Re:I like INFO better (Score:1)
> 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.
LDP howto (Score:1)
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.
Distribution should ADD to LDP... (Score:1)
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.
Re:That's not a GNU-style license! (Score:1)
My mistake, I've skimmed soo many licenses without actually reading them completely I guess it's easy to mix them up.
LK
Re:LDP!! Terrible Docs... (Score:1)
----------------------------------------
A better way is to find what group your modem's serial port belongs to and add your username to that group in
Re:Leases and Maintenance (Score:1)
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
Re:Is the LDP any good? (Score:1)
Re:Authorial Convenience vs. Reader Convenience (Score:1)
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.
--
Re:Authorial Convenience vs. Reader Convenience (Score:1)
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)
Re:Is the LDP any good? (Score:1)
People who want to write docs want people to read them!
Gerv
Book based on HOWTOs (Score:1)
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
I like simple (Score:4)
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.
I LOVE THE LDP (Score:2)
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
Right On, MAN! (Score:2)
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!
LDP!! (Score:1)
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.
Authorial Convenience vs. Reader Convenience (Score:2)
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.
--
That's not a GNU-style license! (Score:2)
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
LPD = good. (Score:2)
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
Is the LDP any good? (Score:4)
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
Documentation where it's needed, MAN (Score:5)
Problem with the LDP (Score:2)
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 -> use pinfo (Score:1)
Re:Right On, MAN! (Score:1)
Info was ahead of it's time (I guess) in terms of being a hypertext documentation system, but really now - the only decent info reader is Emacs, which is really kind of silly. The stand alone info reader is beyond hope, and has perhaps the most counterintuitive interface I've ever seen (only the 'info-mode' commands are available in it IIRC (it's been a while since I've used it, because it sucks)) (I need to look up a flag for grep and the --help-me-please-i-beg-you switches aren't doing the job - I know, I have to start up Emacs, go to info mode, pray the node is linked properly, and then I finally go down 5 nodes to find what I'm looking for Yay! And this, of course, assumes that info pages are put in the right place, and the info directory files are updated appropriately, etc). I seriously think that the GNU project should move towards SGML or something more robust for thier official documentation, but also still produce man pages. Man pages are the most useful, consise form of online documentation I have ever, ever encountered. Info isn't
Actually, one of the SGML packages should grow a facility to generate Man pages from certain sections of the document containing command line switches, etc. I.e. a block of text marked or something would suffice. That way, those long winded authors could write thier 450 node info pages in SGML, and still have a useful, up-to-date man page for those of us who actually work on a schedule....
Dammit (Score:1)
Should have read :
block of text marked or something would suffice.
And to think I even previewed it....
Just a suggestion (Score:1)
David
SGML Tools (Score:1)
Re:LDP quality impedes further Linux growth (Score:1)
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.
"Sorry, we won't let you write anything unless you promise to look after it for the next five years". How is this supposed to help? We don't demand a commitment to maintenance from the authors of the programs we use, why is it so different for authors of the documents?
Could you explain how your proposal would actually solve the problem ouf out-of-date documents? All I can see here is a way of labelling them, and it's usually pretty obvious anyway from the `Last modified' date
LDP home and support at MetaLab (Score:2)
Love and Linux,
Paul
Re:Right On, MAN! (Score:1)
man pages are good, but they're best suited for documenting a specific command, as in "What's that switch for ls to show all files..." When you don't know what the command is called, you don't really want to guess, check a bunch of 'see also' references by loading a new pages, etc..
This is where a HTMLish document is preferable. You select something, check it out, go back, etc. It's suited to putting all of the linux documentation in a big tree and letting you start and browse to what you need. Much more suitable for finding something you don't know the name of.
But, GNU used INFO because there wasn't anything better at the time.
I too think INFO blows. HTML is easier, has more viewers, is very platform independent.
I haven't used DocBook but unless it comes with an HTML version of the documents, it won't be as useful.
I do a lot of my linux work via telnet from windows machines, or in win32 with DJGPP (from work) and unless I want to open a new telnet window just to view docs, I need to have them in an easy to view format, like HTML. And HTML is nicely suited to local or remote viewing.
Re:Easy-to-use SGML tools needed... (Score:1)
AC wrote:
I think the easiest way is to write a short docbook tutorial which spells out the commonly used elements by usage.
Excellent idea. Please check out the FreeBSD Documentation Project Primer [freebsd.org], and in particular, chapter 4.
That pretty much covers it, I think.
N
Re:Right On, MAN! (Score:1)
The Lost Documentation Project? (Score:1)
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!
Re:WTF? (Score:1)
Weird.
Re:Documenting Linux isn't feasible (Score:1)
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.
Re:Authorial Convenience vs. Reader Convenience (Score:1)
>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.
Who said anything about gaining information in the conversion? You can make postscript out of plain ascii text. And when you print it, guess what, it looks like plain ascii. (WHY you'd want to do this is an open question.)
That "much more info" isn't what people read the documentation for, is it? Will multiple fonts help me beat "chat" into submission? (I still dial the modem with minicom and quit out to run the PPP daemon. That sucker's evil.)
The main problem with plain text is that the wordwrapping is fixed, and even then why is that a bad minimum acceptable format if the documentation writer has something interesting to say? If somebody has information I want, I want them to write it up and get it to me, not to be deterred by what format it has to be posted in. Converting formats is the archive's job, not the author's.
And the archive CAN convert. Mechanically if they just MUST have it in format X, and no that doesn't add markup information that the original format didn't have. But you don't have to be a subject matter expert to add markup. A maintainer with time on their hands can take a plain ascii email and re-paragraph it and add boldface and underlining and everyhing, without being an expert in the content. I don't have to know anything about the history of sweedish currency to add markup to a document on the subject, do I? And if I screw something up, I'm sure I'll hear about it in an open environment
Sheesh, with half of the documentation I've seen we're lucky if the author can express their thoughts in english. Rejecting their submission because they didn't chose a format that allows the broadest possible range of fonts to express themselves with just doesn't make sense.
If they pick a format like Word where we wind up LOSING markup information converting to a format we're willing to post... Well, that's the breaks from them using a non-recommended format. But being unwilling to accept submissions that don't have ENOUGH markup capability... Why?
Rob
Re:Documenting Linux isn't feasible (Score:1)
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.
Re:Documenting Linux isn't feasible (Score:1)
(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).
Re:LDP!! Terrible Docs... (Score:1)
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.
WTF? (Score:1)
I like INFO better (Score:1)
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.
LDP and progress (Score:1)
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.
--
Open Source Definition is good for docs too (Score:1)
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...
--
Documenting Linux isn't feasible (Score:1)
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
copyright of LDP (Score:1)
SGML, DocBook, and, Is the LDP any good? (Score:3)
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...
vendor help? (Score:1)
Developing the best feature. (Score:1)
Better than a kick in the arse (Score:1)
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!
Re:Is the LDP any good? (Score:2)
So, what did I do? I mailed the authors of the documents (that's you, Matt, and Larry Greenfield), and the LDP maintainer (at the time, Greg Hankins), asking them if we could take it on.
No response. From anyone.
In the face of that, the group decided to go their own way and write it all from scratch. A wasted opportunity.
I also wrote a whole bunch of ideas down for simple, easy, non-controversial things we could do to make access to the LDP info easier. That want to Greg and Guylhem Anzar (sp?). No meaningful replies. (A few of them are in a separate message.)
So, what The LDP really needs is a coordinator who will answer their e-mail, and *do* something!
Gerv
The One Feature the LDP could really do with... (Score:2)
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
Re:Is the LDP any good? (Score:1)
Point taken. But unmaintained HOWTOs should be promptly moved into the unmaintained section. Sometimes, no documentation is better than bad documentation ( which makes it harder for the newbie to find the right info ). If the LDP would show a greater enthusiasm to can out of date howtos ( ie move them into the unmaintained section ) it would be a good thing.
BTW, IMHO, the best part of the LDP is still the manuals ( ie users guide et al ) even if they are a little out of date.
You're right but... (Score:1)
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.
Leases and Maintenance (Score:1)
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 [thepuffingroup.com]. 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
Re:Documenting Linux isn't feasible (Score:1)
Hey, and that other guy over there running openBSD doesn't have a clue either. What about the BSDi guys? And (god forbid) mac os X which is supposed to be BSD based?
xBSD is no better off for this kinda stuff than linux is. freeBSD might haver better docs than netBSD, just like Caldera has better docs than slackware.
Those issues are not the ones that are important.
Most things work on most linux distro's. its the how do you make it work on any distro (or even the distro of your choice) thats important, and even with the parenthetical piece there much of the information carries over.
contribute already (Score:1)
Re:WTF? (Score:1)
Using preview mode to check things helps, but that actually rewrites what's in the buffer, replacing those codes with the characters they represent. Thus, if you use preview, you have to go back and redo all of your special characters.
--Phil (<viola!>)
Re: Linux docs have a longer life... (Score:1)
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
Online editing (Score:1)
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
LDP needs an active maintainer above anything (Score:2)