Slashdot Mirror
LDP Restructuring and Growing
All in all the LDP endeavors to produce and provide a one-stop source of information relating to the various aspects of Linux. There is now also a search engine on the front page to help you quickly and efficiently locate the documents you need. If you have a question, chances are you will find what you need here.
These documents are produced for you, the end users. That means if there is anything in the documents you find unclear, ambiguous or incorrect you should not hesitate in contacting the author. While the workload of the authors in general may be high and cannot be expected to answer specific problems you may have on your machine, generally authors are only happy to receive feedback on the documents.
Likewise, if you feel you have something to contribute or you wish to try your hands as an LDP author you are welcome to contact the LDP coordinator with your inputs (see the HOWTO-HOWTO). Remember that new documents are produced all the time so it is important to contact the LDP before you start writing in order to eliminate the possibility of duplicate work.
Remember that you do not have to be on-line to read the HOWTOs, in many cases these documents are installed with your Linux distribution and can be found in /usr/doc/HOWTO/
Making things automated and intuitive will be more important. Documentation will be essential to create the future gurus out of the raw material of newbies, but it won't make Linux ready for the masses. Not that making new gurus isn't essential...
Distributions and desktop environments are going to be the ones to make Linux more user friendly. Distibutions particularly, because a well-made distribution can make all the little pieces fit together automatically, where a desktop environment has a more limited involvement.
Unfortunately, they are still no further in the transition from qwertz to DocBook than they were three months ago.
There is not going to be a substantial change in the quality of the material until that happens.
If you're not part of the solution, you're part of the precipitate.
Why would this be a good thing? Because DocBook is vastly more expressive.
Strewing fonts across pages, like chunky peanut butter across bread, does not lead to building decent documents.
It is, on the other hand, reasonably useful to have tags to indicate such things as a filename , application, command line, perhaps even differentiating between what you type in, what the system responds with, and what is a variable to be entered.
If Eric Raymond found it useless, then I daresay that says more about him than it does about the book.
I remember him doing some "bungee management" on the SGMLTools mailing list; he bounced in for a couple days, saying (essentially) that "It's really, really critical that you do these things that I think you need to do," and then bouncing on to whatever else it is that he does. He also spent a lot of time claiming that Trove was tremendously important, and we've not seen a useful release of that yet, after a goodly two years.
If you're not part of the solution, you're part of the precipitate.
> It's insanity like this that makes BSD look kind of appealing.
But then, in the BSD world, if someone's unhappy about something, they do something a bit more positive about it than pronouncing about what needs to be done on slashdot.
I found the move to 2.2 adequately documented. If you didn't, this is perhaps an indication that you're not the sort of person who should be upgrading their kernel by hand? That's one of the things distributions are for, you know.
> build a module--either way)
Yes, and? That's The Linux Way, my friend! I honestly don't see what's painful or ugly about it.
> if things got off the ground
Not quite sure what you're saying here. You do know the LDP has been around for years? And has been functioning well enough during that time? I mean, when I started using Linux in 1994, I knew nothing about Unix save for what I'd read in The Unix Programming Environment. I found the LDP docs very helpful. Although it does occur to me that, since the only Unix I have in-depth experience in is Linux, I tend to look at things in a Linux-centric way. Is that what you're getting at really? That things such as documentation are simply done better in, say, the FreeBSD world? I might agree at least part of the way there. I had a fiddle with FreeBSD recently; I was very impressed with the install program, and the Handbook is very good too.
Yes, I think this is the heart of the matter. As I said, I'm simply not used to anything else -- and what you've never known, you don't miss. Although, now that I think of it, the AS/400 had really nice on-line help...er, yes...
Hmm, yes, so I end up more or less agreeing with you?! That can't be right! ;-)
(But I still think Linux kernel-compiling RULES!)
I wanted to use this opportunity to express my deep love for everybody that runs the LDP and that has ever written a HOWOT, FAQ or mini HOWTO.
;)
I'll send y'all valentines cards or something. But no chocolates this year; money's tight.
-Waldo
Sure. But what happens when you want to publish them on the web, or print them ? Your suggestion that you can just manually edit them ( try it some time !!! ) is not exactly practical. Then if a particular format is preferred it could be converted by the reader.
Simply put, It's not easy to convert all those HOWTOs, especially from a text format which has no logical structure. This goes from inconvenient to a user to simply disastrous for someone who wants to publish all the documents in a book or on a webpage. It also makes updating the documents in the alternate formats a time consuming and expensive process. If this was the way they did it, you would not be able to get the LDP docs in a book or on a website ( or the website would be hideously out of date and unmaintainable ).
Is it really worth putting the users through all that much grief just to save the authors the trouble of reading one page from the HOWTO-HOWTO ? Surely, good documentation first and formost is supposed to make life easy for the readers , and if a little effort on the author's part provides substantial benefits to the readers, isn't it worthwhile ?
Secondly, I'd like to take you up on your point about "learning Linuxdoc". ( You don't need to know anything about Docbook or XML. Linuxdoc is an SGML DTD like HTML ) Linuxdoc is extremely simple, and is a lot like html. It's summed up in one small section of the HOWTO-HOWTO. I learned it more or less instantaneously ( meaning I could go straight to work without wasting time "learning" ).
Sure. You don't do the conversion. sgmltools does it. The whole point of SGML is that it offloads the conversion to an SGML parser.
Why the f*ck does a documentation author have to be an expert in SGML processing, format conversion and other tricks?
One hardly needs to be an expert. You only need to read a page of the HOWTO-HOWTO. HOWTOs are not write-only, you know. I was up and running with Linuxdoc immediately. It is a ridiculously simple DTD. I don't believe someone who is too lazy to learn it will put in the effort to maintain a document, because the effort is somewhere between nothing and very little. As for complaining about "lack of document authors" ... where, and who ? I just submitted and they are swamped with incoming docs.
Instead of complaining,
You're the only one I see complaining.
why the f*ck don't they set up a conversion service, and accept contributions in a number of formats?
Because setting up the conversion service is very nontrivial. And because you simply can't pull logical structure out of an ASCII or Word or badly written HTML document. If you really do XML at work, you don't need to be told this.
Instead, they are proud in beeing able to generate the most useless formats out of their SGML markup graves.
PDF, Postscript, and HTML are hardly "the most useless formats".
But then please stop complaining about the lack of documentation writers!
I think you're misunderstanding my position. I am not complaining. I agree that they don't really have any right to complain either.
The fact that many good authors are just not able to handle the stuff means the loss of potential authors.
Authors that can read the HOWTO-HOWTO will not be lost.
Because plain text doesn't have any logical structure. It is almost impossible to convert. How do you know which text is a second level heading without some kind of directive that says so ? These kinds of directives are the kind of thing SGML takes care of. I hear of logical data rot, where daily GB's of data become unavailable due to loss of reader machines or software and a data format that is proprietory of a company gone bankrupt.
This is exactly the kind of problem SGML addresses. You stay away from proprietary formats. SGML is a W3 standard and is ASCII based. The advantage of SGML is that it allows you to put logical markup in your ASCII file. Basically, all you need to handle SGML is an SGML parser and something to map the tags in your DTD to formatting in your chosen document formats.
Not really true. ( as you'd know if you'd done any serious LaTeX use ). The biggest problem is that finding a picture format that is TeX-friendly and web-friendly is a nontrivial task. It's really the web's fault IMO -- most browsers only display bitmap-based graphics, as opposed to scalable graphics, which means that preparing device independent illustrations that can be viewed in a web browser is not terribly easy. This is a problem, but it's a much broader and bigger problem than you think.
In what format should the illustrations be kept in ? Bitmap formats like JPEG are a problem because they are not scalable ( they degrade when you resize ). Vector graphics formats are a problem because most web browsers don't support them. There is a problem, but solving it involves more than just drawing a few pictures.
At the bottom of each index entry users are encouraged to rate and provide feedback/reviews about the document being indexed.
I hope some folks will go check the OSDI out and let me know what they think. Currently all of the OSWG and most of the LDP documents are in the index, and more are being added daily.
Open Source Writers Group
GNUs-Not-Good?
Then I assume, as a matter of principle, you have no GNU software on your computer, at all, right?
No GCC/EGCS, no GNU command-line utilities, no Gimp, no GNOME, no,...
well, you get the idea.
I'm sad to say I don't quite agree.
Obviously having a large amount of documentation in one place is excellent, and essential for wider take-up of Linux.
However, I don't find their site design user-friendly. The front page particularly is not aimed at people new to the site. We have nearly the whole page taken up with news and recent updates. The links you really want -- guides, FAQs, HOWTOs -- are stuck in the top-left hand corner.
Also, where are the security bulletins? I would have thought that was an essential part of a site like this. I can't even find them under "links". Did I just miss them?
Don't get me wrong, I shall be bookmarking this site and using it. But I don't think it's really ready for a general audience.
11.0010010000111111011010101000100010000101101000
Hmm, RH distributions don't *always* include the How-To's and stuff. The Publishers Edition, which is distribute with RedHat based books saves space by not including the How-To's (or I believe source-code, although there are clear notices that it is freely available).
I've had exactly the problem described at the start of this thread. Although I fortunately have Internet access from work, so I can get hold of what I need, but it can be a pain in the butt from home.
A little planning goes a long way...
Take a look at d.net's new FAQ-o-matic that allows registered users to add a FAQ answer.
Hopefully there's somebody watching over these answers to make sure they're correct, but I think this is a pretty good idea. Maybe the LDP could look at doing something like this.
I just also want to add my two pennies and say thanks to everyone who has contributed to the LDP. It's not perfect, but it has saved my ass many times. Hopefully, one day I'll be clueful enough to add my own contribution. Documentation is a dirty, rotten, thankless job, but without it the best code in the world is useless.
Admit nothing, deny everything and make counter-accusations.
Now what would be cool, is the ability to add feed back, comments etc to documents on line as with the PHP doc for instance. This is a great way to make the docs evolve.
I would suggest that while automation is a good thing, the danger is in tossing choices in favor of ease of automation. What might work well is if there was a documentation system where I could read a HOWTO, decide that a particular solution was appropriate and click on it to "activate". The activation might be a script that does some sanity checking to make sure I'm on the right track, but ultimately it would do exactly what the documentation just told me how to do (perhaps showing me the commands that I could type in the future).
This sort of educational configuration management is what I miss in tools like linuxconf and cfengine.
Also, as a multiple HOWTO author I think you're overstating the difficulty of using this flavor of SGML. There's a bit of boilerplate at the top of the document that you can lift from any other HOWTO, then it's mostly just the nesting sections (<sect>, <sect1>, <sect2>), the <p> to mark the end of the title, and <tscreen><code> ... </code></tscreen> to bracket code samples. There are many other tags, of course, but this is enough to get something that will work with the tools and it doesn't take more than a minutes to convert a text document.
For every complex problem there is an answer that is clear, simple, and wrong. -- H L Mencken
A Linux Knowledge Base of sorts? I tried something like that, using the plain text HOWTOS and directive tags.(~~~AR to:, ~~~PR to:, etc)
Too much work for me! I went back to Doom after a week or so...
.sig: Now legally binding!
SGML has a lot of advantages, which I outline in the HOWTO-HOWTO. In short, it's easy to go from SGML to just about any other format. HTML is primarily for viewing, text can't be formatted easily, and RTF isn't that popular. This makes SGML a logical choice, because you can go from SGML to text, TeX, RTF (and Word), PDF, or even print very easily with little formatting required after converstion.
I wrote my HOWTO (as my abstract says) because I had the same frustration writing docs. It's definately not easy to do, but tools like psgml, LyX, and (hopefully) WP 2000 will make it easier for anyone to write docs.
-- Ever notice that fast-burning fuse looks exactly the same as slow-burning fuse? I didn't... (Edgar Montrose)
Howtos are published in print (not so often anymore, but I do have a Dr. Linux from a few years ago just in case). Plus the HOWTOs are installed or available via CD-ROM on most distributions. Even if you can't get to the net, you can get to /usr/doc/HOWTO. These are usually available in your language and format (HTML, txt, SGML) of your choice.
-Mark
HOWTO HOWTO author
-- Ever notice that fast-burning fuse looks exactly the same as slow-burning fuse? I didn't... (Edgar Montrose)
The point is, companies like Redhat are providing support services for Linux. That's because it needs to be supported! How much does that say to how easy it is to use Linux if a company can base a large part of its business on supporting Linux?
Of course, if Linux wasn't supposed to be used by regular, non-technical users, then it shouldn't be sold that way. I don't see why it couldn't, eventually, though.
The groups doing the GUI development have come a long way and it's looking better and better all the time. But aside from all its other uses like mobile computing, embedded applications, and server computing, does Linux want to become a regular home user's OS? Should Linux strive to be as easy, if not easier to setup and use than Windows and Mac for a non-technical user?
Like I said, all that documentation, as far as a non-technical user is concerned, is just too much. I would say that the documentation is simply going to be the knowledge base of the Linux community to draw from in the interim while developing the easier, simpler and less error-prone generations of Linux in the future.
The Linux Newbie:
;)
:)
The linux newbie was sceptical about the support available to linux users but his friends told him "don't worry, theres plenty of help available". Spurred on by this the newbie stripped out his old O/S and installed linux....
Then he hit a problem; he racked his brains and thought hard: then he remembered what his friends had said:"Just connect to the net and go to linuxdoc.org" this would have been great! - except for his problem - *pppd*
The new page looks great and is quite navigable: go check it out
Ripping an new rectum in the fabric of spacetime.
On a related note, one big problem with documentation in HTML is that it discourages simple graphics. The picture representations (GIF,JPEG) don't rescale for printing, and the main line art represntation, Flash, comes with too much animation baggage. A defined subset of printable monochrome Flash for drawing purposes, a structured draw tool (like Visio or the draw tool in Sun StarOffice) and a tool for turning HTML with Flash into PostScript, would be a big help. This would get Linux documentation away from those endless blocks of text.
Nice site, but why is the font size hard coded to 10 points or so?
Not everyone wants to be able to see an entire HOWTO without having to scroll. If I try to enlarge the fonts in my browser to save myself a little eye strain, absolutely nothing happens.
Come on, don't fall into the form-over-content trap! It's great content after all....
Well, I just looked at the LDP site and I have to say, it looks good. Very navigable, the search engine seems to work. I have to say, though, that I've never been a huge fan of the style that seems to be dominating these days: the page full of news-boxes with a itsy-bitsy nav bar on one side. Nevertheless, it works.
Though I'd hate to make more work for them, I might make one suggestion for the LDP. Since they're hosting just about everything else, what about incorporating a subject indexed RFC archive? It would be nice to be able to get all these things from one place, and the LDP could perhaps do a better job of sorting them than most (ie. preferentially return protocol specs over obscure derivaties of said protocols). I generally use the archive at faqs.org, but their search results are a real pain to wade through.
Just a thought.
Quantum mechanics: the dreams that stuff is made of.
Fine. Then please explain to us how you are going to automatically convert your documents to postscript, tex, ascii, rtf and PDF. Then explain how you would do the same if you had 1000 or so similar documents. Seriously, read the HOWTO-howto ( if you're too lazy to do that, you're probably too lazy to maintain a HOWTO ). SGML isn't that hard ( Linuxdoc is almost exactly the same as html ).
Here are some advantages of SGML:
- Emphasis on logical markup gives the HOWTOs a consistent "look and feel"
- Makes it easy to generate the documents in several formats -- postscript for printing, PDF or html for online reading, rtf for word processor compatibility.
- Makes long term storage more viable. For example, if you used HTML and some HTML tags became deprecated, your documents would be in an obsolete format. With Linuxdoc, you simply change your sgmltools converters to output the newer html / tex / whatever format.
In conclusion, I believe that if there's one thing the LDP got dead-right, it was the choice to use SGML.As many people have mentioned, Linux docs tend to be spread in various directories, in different help systems (man vs. info vs. /usr/doc vs. KDE help. . .) with no unified, searchable interface. Hopefully the next generation of KDE and GNOME help will provide an interface to search all these different sources intelligently by keyword. I know these folks are working on integrating the desktop help with man pages, but that's still not quite enough. I see bad help interfaces as one of the worst problems facing Linux/Unix desktops right now.
I know that ht/dig has been modified (for KDevelop via CoSource) to search local, rather than web based, files. I'd also love to see some really good, comprehensive, system-wide FAQs that tie into the rest of the help system ("How do I install a new network card?" links to the right part of the linux-networking HOWTO, etc).
--JRZ
From personal experience HOWTOs are great, but they can also be a lot of work to read just to get something working. However the great thing about HOWTOs is that they are generally structured and might lend themselves to an idea I call "automated HOWTOs".
One reason Windows is popular is that Microsoft keeps finding new ways to make it easy to use the system. Ok, easy to crash too, but hey. If somebody were to take a particular HOWTO, and rework it into a script, it might turn out to be something vastly more useful for new Linux users who are used to Windows doing everything for you with its wizards and such.
I'm not a journalist, but I play one on slashdot
The problem is that you have lots of distributions, each of which do things a bit differently. Such as having files in different places, etc. So someone would have to write a different script for each one, and many of them would probably get left out.
/etc/resolve.conf, or runlevels, you know it). This also encourages people to learn, because they have to gain knowledge in order to achieve some desired functionality from their system. I view this as a Good Thing--knowledge being power, and whatnot. Plus, it will help you if you want to get a job later, and need to do something on a Sun box that doesn't have nifty scripts.
:)
I personally encourage people to get in there and hand-edit text files. This method works for every distribution, and many times can be applied even to proprietary *nixes (if you know how to edit
Distros like RedHat provide GUI tools for such purposes, and they should also provide the documentation for using those tools (they do). I would rather see the general documentation remain...well, general
WMBC freeform/independent online radio.
Documentation is something most coders hate, but without the docs how the hell are we gonna encourage newbies to use our software?
;-)
The LDP does a great job of collecting all the relevent docs into one place but more often than not the how-to's wouldn't be needed if the guys on the project started to document there stuff better. how many times have you seen the install file say build it and use it or some such crap?
I recently installed a nameless piece of software that had a 10 line readme file! one line said if you don't know how to do this don't! what the f*** how the hell is this meant to encourage use?
We (the coders) need to start writing a little more, or at least finding a guy/gal who can write. Well I know what I am gonna have to do WRITE SOME DOCS lol.
sparkes
PS get in touch with you LUG to find willing doc writers! thats what I do
*** www.linuxuk.co.uk relaunches 1 Mar 2000 ***
blog and junk
OK, as a long-term Unix user (and later professional admin), I've gotta say that the LDP attempts to solve one of Linux's biggest drawbacks--in a typically Linux way.
Documentation for Linux has been hard to find, spotty, uneven, frequently outdated, and inconsistent. Now, thanks to the LDP, we have easy (or easier) to find, spotty, uneven, frequently outdated, and inconsistent documentation! Joy!
Don't get me wrong here. Things are moving forward. The LDP is definitely a step in the right direction. The authors of the documentation that does exist should be highly commended for doing the work that (almost) no one else wants to do. My hat's off to them!
However, online documentation for Linux is definitely weak, and fundamentally inconsistent. In fact, this is probably the biggest flaw with the Open Source philosophy--different bits (of code or of documentation) are written by different people with different abilities and different ideas about how to do things. (Not to mention a different command of the english language, given how global linux is.) The end result is that two items of documentation are different. Two conceptually similar bits of code end up being different. (Ever noticed that when building a kernel, 'make install' and 'make modules_install' behave in vastly different ways?)
The point of all of this rambling is this: The next step for the LDP (aside from making guides and how-tos take up more than 5% of the opening page) is to move from being a clearinghouse to being an editor. Just like Linus approving kernel mods in official distributions, all documentation should be initially checked for adherence to a standard format (including correctness and grammar, by the way), and then CONTINUALLY CHECKED for ongoing validity! If a doc becomes out of date, then it should be moved into an area (and category) clearly marked, "out of date HOWTOs." In fact, there could be an open call for anyone who wanted to update them. I'm picturing something like, "please contact us if you wish to update any of the following docs." If updated (and gone through the process again), then it would be put back into the 'current' list.
The bottom line is that the open source way of doing things doesn't _inherently_ have to be scattered and inconsistent, but _tends_ to that end without explicit and considerable effort to stop it from happening.
And sure it's a big project, but isn't that one of the biggest advantages of open source?
Sorry for the length. I'll shut up now.
"People who do stupid things with hazardous materials often die." -- Jim Davidson on alt.folklore.urban