The LDP Responds to Suggestions

Guylhem Aznar, one of the folks over at the Linux Documentation Project has sent us an updated list of features/responses/additions that they've put into the project. Much of this work comes as a result of Slashdot suggestions; you can read more below and perhaps want to sign up to help out.

Thanks a lot to Slashdot readers for the comments they submitted.

Our announcement may have seemed "empty" but you provided us with lots of good feedback regarding the LDP in general, and that will help us in improving our quality.

While reading the comments, I took a paper and wrote down the different problems people had.

Some will not be solved immediately, some are now solved, others are outside our scope while others can be solved if we get more people to help in the effort.

- web site design : FIXED

Each of your comments were precious to help us improve its appearance and ease of use. Please try out the new version.

- provide direct access to important links : FIXED

We now have big links for each of the major document types (HOWTOs, FAQs...) on the first page. Please check "non-English" where you should find a link to your local LDP with translated documents.

- provide security bulletins & link to RFC archives

I'm sorry, but this is not within the current goals of the LDP. However, we will add links to other sites with this information in our "Links" section.

- provide DocBook and PDF documents : FIXED (Docbook format and ">PDF format are online now

I converted each of the LinuxDoc HOWTOs and mini HOWTOs to DocBook and PDF, uploaded them two days after the Slashdot article ; they are now available on each of the formats as another output, just like the html and ps versions.

- move to DocBook because LinuxDoc sucks - stick to LinuxDoc because DocBook sucks

The HOWTOs are now provided in both LinuxDoc and DocBook; however for the moment we can only accept LinuxDoc source for the HOWTOs.

In the next weeks both DocBook and LinuxDoc SGML source will be accepted for the HOWTOs. We are currently testing DocBook output formats.

You can already submit your DocBook only document which will be put in the DOCBOOK section. (a new major section, like FAQs and HOWTOs)

- "tables don't scale to window size and resolution and 10 pt font size is hardcoded

Our Webmasters are working on these problems.

- How can I submit my work to the LDP? You can read the HOWTO-HOWTO

three possibilities depending on the format:

a. you can write in LinuxDoc : call your document an HOWTO b. you can write in DocBook : call your document a DOCBOOK :-) c. you are a master of TeX/LaTeX, pdf or any specific format : call your document a GUIDE or a FAQ, depending on its contents.

Please use a license compatible with our requirements (GNU Free Documentation License is IMHO the best choice but feel free to take any other license) and mail your document to ldp-submit@lists.linuxdoc.org

If your LinuxDoc or DocBook source contains errors, I'm sorry but we will not process it until the errors are fixed. Please test it first

- You should check the documents : FIXED

We have since November! We would like to be able to have our peer review team proofread each submitted document.

However, there are far too many docs submitted to ldp-submit for our small team to adequately proofread each document. If you would like to help us please subscribe to ldp-submit (mail ldp-submit-request@lists.linuxdoc.org).

- XXXX and YYYY HOWTOs are outdated/unmaintained

Please update the document and submit the new version to the LDP if the license allows modifications. We will be happy to include your new version (News HOWTO and SCSI HOWTO are especially old!).

- I just found ZZZZ HOWTO which is not part of the LDP yet

Then please contact the author and ask him to send his document to ldp-submit@lists.linuxdoc.org Chances are we will include it, unless it contains errors, has a non- free license, or duplicates an existing document.

- license problem, GNU/Linux... FIXED

We have a manifesto and a license guide on the first page. There is an ongoing discussion and both may be revised.

We will not impose any license but rather have some criteria and requirements (free redistribution for ex.)

And if you don't like "LDP", just remember netscape/mozilla : it's written LDP but it reads GNU Linux Documentation Project.

Writing documentation is not as sexy as writing software (To quote a Slashdotter, "Honestly, how many users want to read documentation? How many of them see a fat manual and feel happy?")

We do need more authors. Unfortunately, not everyone can be a good author. It requires a combination of writing skills, technical knowledge, and the willingness to accept criticism that improves your final product. Thank you all for your responses--we hope that you continue to let us know your opinions on the LDP.

Comments

Re:MSDN for Linux

[Jon Peterson]

"The relevant results will come up immediately because it will have a very high relevance coefficient. "

That's not really true, is it. MSDN and technet are pretty good. It's depressing the number of times you search for a problem on the net and find 50 pointers to different archives of the same mailing list, all of which reveal someone with exactly the same problem as you - someone who got no response from the mailing list beyond a couple of 'me too' followups.

More to the point, MSDN/Technet is simply more convenient. There's alot to be said for putting some of that stuff on CD-Rom and giving it a real search engine. Imagine something like all the documentation of every app in a standard Linux distribution on CD-Rom. With a proper search engine. Properly searchable Man pages would be a start, but then add to that the contents of every user-foo and admin-foo and devel-foo mailing list archive for each application. Then add to that all the documentation branches of the applications' respective home pages. Then add all the howto's and the rest.

Then update the CD-set quarterly or bi-monthly. Sounds like a useful thing to me.

If I had to choose MSDN style or Internet style, I'd probably go for Internet - but both together would be much nicer than either on it's own. Sitting around saying "No Linux documentation? Just search the ***ing net man" is actually not too helpful.

So, gratz to the LDP, but if anyone's looking for business plan I'd go for a Linux Technet CD-Rom set. Errr, only I use Solaris at work. But otherwise I would :-)

Limit redundancy?

[Lettuce B. Qrious]

This may not be the proper forum for this, but since I've felt frustrated by this on numerous occasions, I need to vent;

When I run RedHat 6.1, I truly and honestly don't give a rats ass about how things are done with Linux Kernel 1.7.009 or Debian/Suse/Slackware or whatnot. I don't know how many times I've gone through a document only to find that nothing (or little) within it applies to my problem.

The ultimate functionality enhancer for Linux documentation, would be an interface where you specify whatever hardware/software setup that applies to you, and then get documentation specifically for that purpose.

However, this may be a point more suited for attention from the distributors. RedHat indiscriminatorily doles out a ton of HowTo's that for a large part do little but waste its customer's time, and if someone starts doing this better, I'll switch in a New York minute. The product from the distros should be facilitation of setup and maintenance, not randomly collected material of little relevance...

Oh, and by the way, adding a "Troubleshooting"-section to the howto's would be a blessing for newbies...

Documentation Forum.

[Dr. Evil]

It would be nice if LDP followed something similar to Slashdot or Freshmeat whereupon people could comment or ask questions if they run into trouble. The authors can't update the docs all the time. If we could communicate the trials and tribulations while working with a package, it could provide valuable feedback to the document writer and the developers.

Also if you have a chapter to contribute or propose, post it and wait for it to be integrated or ignored.

Putting up a two-year-old dead document may not be very useful, nor are you going to have experts on the topic critiquing the work. On the other hand, if somebody posts, "Hey, the feature described in section 3.2 has been changed!", or "see CERT advisory 2000-09-12.3!" it is better that it be found in a dedicated forum than through hours of probing on IRC or searching through Usenet.

I thought I posted this idea to the original suggestions...

Not as sexy?

[SurfsUp]

Writing documentation is not as sexy as writing software (To quote a Slashdotter, "Honestly, how many users want to read documentation? How many of them see a fat manual and feel happy?")

Hmmph. Software that is crap because of lack of adequate documentation is not very sexy at all. Said users, if they want to use sexy software, better learn to see the beauty of good documentation. It's not first and foremost for the users (*learn to program first!*), it's for the hackers that make Linux the sexy system it is today. Of course, it sure doesn't hurt users to be able to find out how there systems work when they want to, in as much detail as they want to.

I thank everyone involved in LCP profusely, but I'm not getting involved - I'll respectfully keep hacking on my own project, and I promise to write proper draft documentation for it when it's done.

Slashdotted already....

[SgtPepper]

oh man.....they should have a Withstanding-The-Slashdot-Effect-HOWTO


Sgt Pepper
Lame Sig Shamelessly Ripped from
Fortune:

I can hire one half of the working class to kill the other half.
-- Jay Gould

Sign UP

[reality-bytes]

They will need a lot of help.

The Linux Documentation Project will need all the help it can get; this at the moment can only be an uphill struggle. Linux software development is undoubtedly at its most prolific it has ever been so as soon as something is documented; it will have been revised (something that LDP have taken note of)
It seems therefore that the only way to win this is to increase the manpower available and signup to help...

I emplore /. readers who have knowledge and experience of related issues to get involed (get their keyboard dirty) and be part of the big picture :)
Linuxdoc.org has already proved invaluble to me so I will be doing whatever I can.....

MSDN for Linux

[zero-one]

Has anyone tried making something like a MSDN library for Linux? This is one of the things that is really nice about programming for Windows (esp. when developing using a pay per minute internet connection). Having everything in one place (including journal articals) makes finding obscure information so much easier.

Re:MSDN for Linux

[arivanov]

No need.

Linux is an Internet OS. All the info is on the net. If you know how to ask google you will get the answer immediately because google indexes an insane number of copies of the lkm, linux-net, etc archives. The relevant results will come up immediately because it will have a very high relevance coefficient.

This is light years ahead of MSDN. In terms of both technology and speed at which you obtain results.

Re:Categorization by filetype?

[coyote-san]

That categorization is required *because* the LDP is a documentation effort. The results should be usable on web servers, printed material, PDAs, and the Goodyear Blimp if required.

Documents written in HTML will remain in HTML. Documents written in TeX will convert to text and postscript, but not info format (modulo the use of texinfo macros, of course).

LinuxDoc and DocBook can be a real pain, but these formats are designed to be sufficiently abstract that the documents can be converted to any reasonable format. That means it's far more likely that a HOWTO will be maintained for the indefinite future, while a GUIDE may be dropped once the author moves to a new format himself.

Vote.

[Black Parrot]

Be sure to check out their page, because they have a link to a site where you can vote on which open project will get funding from the proceedes of an LDP-based book.

--

Semi Broken "Plain Text"

[jandrese]

Some of the plain text pages on the site seem to assume that whatever you're browsing with has terminal control code capability. For instace: from the X modeline howto:

33.. TToooollss ffoorr AAuuttoommaattiicc CCoommppuuttaattiioonn

What you don't see there in Netscape are the character control codes that only work on terminals.

One suggestion was unfortunately ingnored...

[Anonymous Coward]

Here we go again:

We do need more authors.

Then please make it easier for authors to contribute. Setting up the whole SGML tool-chain is a major desaster. Having to write in SGML is a desaster, too.

You will not attract a huge bunch of professional technical writers if you don't lower the bar. "All" you will get are the programmers who are just a little bit tired of coding and who relax by glueing together some documentation.

Re:One suggestion was unfortunately ingnored...

[doom]

I agree that this is a problem. The SGML tools that you need to use to write a HOWTO may actually be no big deal, but I do know that the need to learn them is the thing that made me go "maybe I'll get to this later".

On the other hand, I'm pretty sure that they'll take "Mini-Howtos" written in HTML. So maybe I should've just called my stuff a "mini" and sent it in? Yeah, here's the policy from the HOWTO-HOWTO:

Also note that all HOWTO submissions must be in SGML format (currently using the LinuxDoc DTD). The mini-HOWTO submissions may be made in either SGML or HTML formats, but only SGML-formatted submissions will be included in printed versions of the HOWTOs.

It could be that this is the key development that will "lower the bar": Also from the HOWTO-HOWTO:

Programs like LyX (right now my LinuxDoc editor of choice) allow you to write in TeX format, then export it as SGML and render from SGML to whatever you chose.

Here's the place to look for Lyx: http://www.lyx.org/

My humble suggestions for LDP web site

[Kurt Gray]

First let me say I applaud the LPD and all the work that has gone into it -- I've used it many times myself and always intended on contributing docs to it but it's on my list of things to do like exercise more often and get a life.

Second, I have a humble suggestion: the front page of the site should be written with the newbie Linux user in mind. Think in terms of a brand new Linux users who is trying to figure out how to format a floopy disk, transfer files from his Windows drive, or read files from a CDROM. As soon as Joe Newbie hits the front page he should know where to go next. Unfortunately the current page design the most useful links are crammed up in the top left corner of the page, and the prime realestate is being used for the News column on the front page, which is basically the webmasters journal, although interesting, should not be the fropnt page of the site -- save that for the What's New page.

So I would humbly suggest the front page be a Yahoo-like category index of the various kinds of documentation on the site -- put the table of contents on the front page in plain view.

Other notes on DocBook

[Mark F. Komarinski]

I'd like to point out that those of you that struggled with LinuxDoc, either getting it installed or running, will have fewer problems with DocBook, mostly because it is so well documented. One excellent resource is the DocBook: The Difinitive Guide from ORA, available at your local dead tree store and online at www.docbook.org.

Categorization by filetype?

[LetterJ]

This part bothered me a bit:

a. you can write in LinuxDoc : call your document an HOWTO b. you can write in DocBook : call your document a DOCBOOK :-) c. you are a master of TeX/LaTeX, pdf or any specific format : call your document a GUIDE or a FAQ, depending on its contents.

Why are the documents being titled according to filetype first, and contents second. That's like Yahoo categorizing sites by whether they use PHP or Perl, and not by what the site is about.

Yes, I realize that they are still considering content, however, the quoted statement indicates that the title category is decided by the file format. "I'm looking for a HOWTO on ???. What? I need the GUIDE instead? There's no HOWTO because the expert doesn't use the right file format?" Good documentation relies on consistency. I thought that was one of the main points for the LDP: you can go there to get all of your questions answered. Companies like O'Reilly have it figured out. All of their "???? in a Nutshell" books are fairly similar in style and content. You can intuit from the title category what type of book it is. You ought to be able to do the same with LDP documents.

I'm sure someone will ask why I don't have any HOWTO's in the LDP.

1. When I first went to contribute, I found tons of stuff on making sure that I got the file format(s) properly set. However, I couldn't find much of anything on a suggested content outline, organizational structure, suggested content, etc. All of those things are important to create consistent documentation.
   
2. I'm not an expert on much Linux related.
   
3. As people tend to get a little touchy about a complete rewrite of their HOWTO, helping on existing one's isn't welcomed.
   
4. I spend enough time on the job writing doc, I'd rather write PHP apps in my free time.
   

LetterJ