LDP Restructuring and Growing

Guylhem Aznar writes " After some restructuring of the Linux Documentation Project (LDP) we feel ready to serve the Linux community from our new home. The LDP has collected and produced numerous documents such as guides, HOWTOs and mini-HOWTOs, FAQs pages, and more. " Continues in article body...

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/

Comments

Re:Still SGML is required...

[elflord]

I'd rather drop dead than wasting my time with SGML. I have written a nice sed tutorial some time ago, which I would contribute, but not in SGML.

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.

Biggest problems with linux documentation:

[JohnZed]

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

automated HOWTOs

[Marvin_OScribbley]

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.

This would be hard

[autechre]

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.

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 /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.

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 :)

Open source docs

[sparkes]

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 ***

ONE step in the right direction...

[swordgeek]

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.