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 [e-mail]

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 [e-mail]).

- 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 [e-mail] 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.

Re:MSDN for Linux

[yugami]

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.

Actually there is a group thats working one something like this.

actually, they are working on a standard for opensource documentation formatting. and thinking about acting as a central repository. they will have tools to convert too and from their format(docbook? last i heard) to older/legacy formats

as a part of this there was discussion for working on a search engine/framework for looking at the documentation on your system(so you can keep everything on your system, or look at the internet version)

I'm afraid that I cannot remember their name off the top of my head. they have a mailing list that I read from time to time.

something like Open Documentation Environment(ODE)

Increasing the quality of program documentation.

[commbat]

Slightly OT, but I think I've thought of one answer to the bad docs problem:

As reported somewhere a while back, open source programmers do it for the respect they get from others in the open source community. Now, if the respect they get for their programming was also tied to their document writing I believe we would see an immediate and enormous increase in the quality of documentation.

However, I believe that we end users can't effect this change of attitude by ourselves, it has to come from the top. Face it, the programmers aren't looking for OUR respect, the want it from the people THEY respect. But this has another problem, the open source programming leaders themselves aren't known for their stellar document writing (if they were, we probably wouldn't even need this discussion because there wouldn't even be a problem with documentation.)

Now if we could get Linus and Alan and ESR and RMS and all those other luminaries in the open source movement to start leading by example in the document-writing area the problem would start to fix itself.

(If I've unfairly grouped someone who already documents their programs with those who don't, I'm sorry in advance.)

Re:Big and thick.

[Stary]

Sure, I agree to lots of what youre saying, but...

Also, as others point out, electronic documentation isn't very helpful when my problem revolves around the computer not operating.

In this case, a CD will be equally worthless, wont it? And if you're talking about the newbie that cant get his box online, then a CD will be equally worthless for the newbie that doesn't know how to mount his CD's filesystem.

In general though, I think a CD collection with everything in one place, properly indexed with a good search engine would be a great thing.

Re:MSDN for Linux

[QZS4]

do you know know about the -K (that's a capital) switch for man?

No, and it doesn't seem like I'll ever find out what it's supposed to do:

~>man -K
man: invalid option -- K

But I think manpages rule anyway. Always the same sections in the same order, and everything on one page, easily searched in less. Compare that to the absolutely horrible "info" format, where the information is split up into myriads of small sections, and you have to navigate yourself to death before you find what you're looking for. And when you've found it, there's no easy way to get to the other stuff you wanted to know, which means even more frustrating navigation.

And as a special bonus, its very easy to get a nice-looking hardcopy of a manpage, just use "man -Tps proggie | lpr". (I am definately not a big fan of info, does that show? :))

Be Dynamic

[jfwcc]

-
I have to correct something in regard to this reply:

I never said, or at least I never ment to, that statical linked systems, apps,... are better.

Of course I prefer the state-of-the-art dynamical architecture.

I just wanted to point out, how difficult it is to keep pace.

BTW, you CAN NOT download and upgrade glibc from RedHat.
george./

Re:Why no easy solution RE:Software level & Doc le

[IntlHarvester]

If you are clued in enough to want to upgrade your glibc, you are more than clued in enough to know that RedHat upgrades can be downloaded for free or purchased for two bucks from cheapbytes.

If you want a distribution that is all statically linked, go for it and make your own. Call it "Primitive Linux", or something and you'll probably find a fan base. I'll stick to dynamic linking and performing OS upgrades, myself.
--

Software level & Doc level

[PingXao]

I've been trying to upgrade a system from glibc-2.0.7 to glibc-2.1.2. The HOWTO and other misc. docs on doing this are woefully inadequate. They're probably woefully inadequate for most things libc-related. The HOWTO - which did help me when I initially installed 2.0.7 - stops right AT version 2.0.7. Now what do I do? I've been hacking with linux for > 3 yrs now and I can't figure it out. What's a *new* user supposed to do?

After going through the painful process of getting libc5 to peacefully coexist with libc6 about 18 months ago, I thought that any future glibc upgrades would be less painful. Hah!

I read the INSTALL doc, searched the web, finally went to deja where a search of the "gnu.*,linux.*,comp.os.linux.*,comp.os.linux.*" groups led me to conclude that the only way to upgrade to glibc-2.1.2 reliably is to upgrade the whole distro from square one. This is totally unacceptable, IMO, and even though I successfully installed gcc-2.95(?) there doesn't seem to be a clear map as to how to proceed from here. What's the next step? Note that glibc-2.1.2 BUILT SUCCESSFULLY but how the hell do I install it on a live working system as the new default libc?

This is only one example of how frustrating linux can be. A clear set of docs is a MUST for linux to prosper and I don't see it happening. People are lazy and writing documentation is the last thing anyone wants to do. Absent an army of paid technical writers nothing is ever going to develop along the lines of the MSDN library. This more than anything will stifle linux's growth, mark my words.

The original referenced LDP article recommends (paraphrasing) "Don't lay out a template with holes to be filled in later - this will ensure it never gets done". I think just as important as an organized 'what IS available list' should be a 'what IS NOT available' list. Does that really differ from an outline with gaps that need to be filled in?

You are right, but what about newbies ?

[jfwcc]

-
the difficulties I pointed out are the same you mentioned.

How many folks have the time to recompile all their pgms ?
I don't.

What is YOUR ADVICE for a LINUX-NEWBIE ?

Always re-installing new versions ?

I see this as a problem for Linux to get on more desktops,
which is the goal of many Slashdot readers, isn't it ?

So WHAT DO YOU DO when XFree 4x, kernel 2.3, KOffice etc. come out ?

Do you upgrade your stuff for a week,
or do you re-install, saving your data ?

What do you answer to a newbie who wants to run an application that requires a higher libc ?

Although I'm a pro, I want to USE my machines,
not to be forced to upgrade every week.
Maybe I'm getting old --- but that is also what new Linux users want.

And why they hesitate, because in a few months something better will be availabe.
My answer is dumb: wait until the new distribution is out, then never read anything about improvements anymore.

Just when you buy a PC.
A week later you find a better or cheaper one.

New users are not used to upgrade every month.
They want to install something, and live in peace for the next 5 years.

I really think this is a big problem for Linux to go mainstream.

And I REALLY like to read your answers,
thanks,
george./

Re:MSDN for Linux

[orcrist]

i'd like to see an iso image of the ldp, and all it contains, have it be searchable, indexed, and running locally on a live webhost, etc.

I don't know about the other distros, but SuSE has at least a good portion of the LDP included, and if you install the whole help system, at least everything in HTML is indexed in a full-text search.

If you install dochost, and... well everything in the doc series, you end up with a pretty decent amount of documentation accessible and searchable from the default Apache start page. I'd be pretty surprised if the other distros don't have something comparable.

Chris

Re:Increasing the quality of program documentation

[mcrandello]

""Now if we could get Linus and Alan and ESR and RMS and all those other luminaries in the open source movement to start leading by example in the document-writing area the problem would start to fix itself. ""

Personally I would rather them *not* spend the time trying to write documentation at the level that end-users will all (or even mostly) be able to understand. That would mean longer waits between upgrades, patches and more good programs. However I do think *someone* has to do it. Maybe they could take on interns...people who they could give notes to who could cobble together some human-readable docs for the rest of the world. Frankly I'm amazed that none of all the newfound Linux-IPO money hasn't been doing this yet (maybe they are, but I haven't read about it on /. (-:)



[e-mail]
rschaar{at}pegasus.cc.ucf.edu if it's important.

Re:Big and thick.

[TrentC]

To quote a Slashdotter, "Honestly, how many users want to read documentation? How many of them see a fat manual and feel happy?"

Am I the only one that falls into that category?

No.

Excessive documentation turns me on.

While I wouldn't go that far, I will say that I love curling up with a book and just reading. I'll absorb info over time, and at the very least get a feel for where I can find the info I need the next time I'm sitting down at the computer.

Also, as others point out, electronic documentation isn't very helpful when my problem revolves around the computer not operating.

Jay (=

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

Re:Slashdotted already....

[nijhof]

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

As in Please use a mirror?

Jeroen Nijhof

Re:One suggestion was unfortunately ingnored...

[TrentC]

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.

Amen. And it doen't have to be the "professional technical writers" that get scared away. People like myself, who get frustrated with the lack of documentation (or are unable to figure out where to find it) that exists for whatever problem I'm having, who plan to take notes as I bang some of this stuff out and work it into a least a mini-HOWTO, will not feel like learning SGML just to make their contributions "worthwhile".

Jay (=

Re:One suggestion was unfortunately ingnored...

[fingal]

I'm not an expert, but it seems from a quick glance that lyx has a linuxdoc compatible mode so you should be able to generate all the documentation you like inside a nice cosy graphical editor.

(apologies if i'm missing something basic and fundamental - it's been a long day)

Re:MSDN for Linux

[mysticbob]

i disagree. there really _is_ a need for something like this. i'm offline so much of the time, in a cafe, on an airplane, etc, that if i need to search any and all linux documentation, i _have_ to have it with me. as the previous author noted, there are other motivations for having a complete copy offline too, such as expensive connections, and i'm sure there are others.

i'd like to see an iso image of the ldp, and all it contains, have it be searchable, indexed, and running locally on a live webhost, etc.

one completely exellent tool that i've used for years which does this, but for IRIX, is the IRIX developer's toolbox. there's an online mechanism, and a mirror which you can get cds of, and use offline. excellent tool for IRIX devrs (and lots of code for stuff like opengl too). check out:

http://toolbox.sgi.com [sgi.com]

i'm curious if other slashdotters who work offline would find a tool like this (say ldp on a cd) useful.

it's about time

[jnazario]

seriously, how long did you guys think it was worth it to keep the links to the documents *buried* on the pages?

and as for the quality of the documents, well, i've written a few that i should submit, but honestly, i doubt i will. in general there has got to be something of a standard for document quality. too many of the HOW-TO's are so poorly written.. blech.

thanks for the site changes, and thanks for being less exclusive about the document formatting.

Re:Semi Broken "Plain Text"

[whoop]

Nah, those are howtos for slow people...

Re:Software level & Doc level

[Digital Mage]

Well, I feel a little better knowing that I'm not the only one who has problems getting libc and glibc upgrades to work as they should on an already existing system. (I got frustrated enough to jump to a new distro).

Upgrading major components is one of the biggest problems in working with linux. I just love spending hours of my time resolving package dependencies to the point of frustration (note the sarcasm here). The documentation is of *some* help but there isn't enough in the major-component-upgrade area.

What would be nice is an upgrade utility that sits on top of the package manager that can take care of the upgrade dependencies for the user. And if it can go out on the internet to grab these new files it would save people a lot of time. Sorry, off topic.

A list of 'what IS NOT available' might spur people to write the documentation on it more than empty holes. The empty holes suggest that the documentation will be filled in later by the same person who did the documentation. What we really need is a list of items that need documentation submission by the community so that the 'holes' can be filled in.

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

Re:One suggestion was unfortunately ingnored...

[stephend]

On one level I agree with you. It took me ages to get most of the tools working properly, and I'm still not completely happy (I can now get PS format, but PDF still comes out as a muddled mess).

However, allowing authors to submit documentation in any format they see fit is a non-starter. You need some level of consistency in order to manage the volume of documents -- try handling a mish-mash of Word, SGML, HTML and plain-text files!

I think more effort is needed on the tools to make them work better. There's nothing wrong with SGML (I only claim to know enough to write a HOWTO and no more), and anyone that's technically competent enough to document Linux is up to the job of learning it.

And finally, I don't think we need 'professional writers' as such. The current policy of accepting text in 'readable' English seems fine to me, although a little more editing probably wouldn't go amiss.

PDFs are broken

[elflord]

I'm the author of the font HOWTO. It appears the PDFs are broken. FYI, here's how I convert to PDF:
sgml2latex --output=tex index.sgml
sed -e '/\\usepackage{t1enc}/d' \
-e '/\\usepackage{babel}/d' \
-e '/\\usepackage[latin1]/d' \
-e 's/\\usepackage{null}/\\usepackage{null}\\usepacka ge{hyperref}/' \
index.tex > index2.tex
mv index2.tex index.tex
pdflatex index.tex

This seems to generate good PDF files ( at least with my HOWTO, it does )

Re:LDP runs on Solaris?

[Drey]

Yeah, it's running Apache for certain, dunno about the OS:

[74]~> telnet www.linuxdoc.org 80
Trying 152.19.254.81...
Connected to www.linuxdoc.org.
Escape character is '^]'.
GET / HTTP/1.0

HTTP/1.1 200 OK
Date: Mon, 21 Feb 2000 18:56:34 GMT
Server: Apache/1.3.4 (Unix) PHP/3.0.6 mod_perl/1.17
Last-Modified: Wed, 02 Feb 2000 16:09:58 GMT
ETag: "51-226d-389856d6"
Accept-Ranges: bytes
Content-Length: 8813
Connection: close
Content-Type: text/html
.
.
.

--
Making iDirt 1.82 a safer place, one bug at a time.

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.

Suggestion: Matchmaker section

[Wench]

OK, so people who can write are needed. Personally I can write. I code during the day at work. I'm also busy and I don't have time to trawl through pile of documents trying to think up a project to write something about.

So how about adding a "Coder seeks Writer" / "Writer seeks Coder" section? Match us up. We can email each other with suggestions and drafts and questions, and hopefully get stuff much better documented.

Why categorization by filetype?

[Christopher B. Brown]

... Because that allows them to divide and conquer based on what they have analysis tools for.

Remember that those O'Reilly books have considerable structure in common; they are all of similar form factors, which means that you can readily drop them onto a single shelf and expect them to fit nicely. If they had varying shapes, sizes, and bindings, this wouldn't work out nearly so well, as they'd need to (for instance) come up with a customized kind of book binding for each book.

If your docs are written using LaTeX, they have no way of automatically integrating it into a single comprehensive document.

If your docs are written using whichever DTD they favor today, it is a relatively straightforward task to integrate this together.

Thus, there are actually two classes of documents:

• Documents using the SGML DTD that they favor, and
• Those that don't, for which an important priority will be to figure out if the documentation is, based on its format, going to be useful to you.

Re:One suggestion was unfortunately ingnored...

[elflord]

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.

What the hell is a "desaster" ? Anyway, writing in LinuxDoc isn't very hard. Anyone who's written in HTML before can pick it up in minutes. ( "writing in SGML" doesn't make much sense. One writes to an SGML DTD like LinuxDoc, HTML, or Docbook ) For those who can't handle the simple task of learning a simple DTD, there's Lyx ( it'd be good if they'd point to Lyx as an authoring tool )

I am curious as to what format you'd propose over LinuxDoc or Docbook. The requirements are that it should be convertable into several formats, and it should have some logical structure ( so that you can convert it ).

You will not attract a huge bunch of professional technical writers if you don't lower the bar.

I don't like the idea of making the bar too low. I wouldn't want someone who is unwilling to spend a few minutes reading the HOWTO-HOWTO as a HOWTO maintainer ( you know, HOWTOs are not write-only )

Re:Increasing the quality of program documentation

[jaed]

Maybe they could take on interns...people who they could give notes to who could cobble together some human-readable docs for the rest of the world.

As long as that attitude toward documentation prevails among Linux users and Linux programmers, the quality of the documentation won't improve much.

Really, think about what you're saying here. You suggest getting "interns" to "cobble together" something. How would you feel about taking any other kind of skilled work and recommending that you just get a few cheap interns to slap something together? Do you think the people who are skilled at that work would appreciate that? Do you think they'd be eager to use their skills for the benefit of a community that derogates those skills?

(And don't think programmers can do it, either. The programmer is obviously one of the best sources of information about how the program works, and most programmers can write reasonably well...but most don't know much about indexing or data chunking or the distinctions between task-based and conceptual documentation. Reasonable, since it's not their field or area of interest. But it means the best documentation doesn't usually come from the programmer, even if the programmer can write well and decides to take the time to do documentation. Neither of which is a sure shot. And of course there's the problem that the programmer's viewpoint is hopelessly "contaminated" when it comes to seeing the program through a new user's eyes.)

ESR talks a lot about the reward of prestige. If you want to see why some areas of Linux development excel while others lag behind, look at the prestige given to working in those areas. Are technical writers given deference for their skills? Can anyone here even imagine anyone getting remotely the respect for writing and organizing documentation that you do for writing a device driver? (Can anyone here imagine someone whose contribution was writing kick-ass, open source user documentation getting stock options in an IPO for that contribution?)

Before the state of documentation changes much, I think the attitude will have to change. When excellent writers who can untangle complicated procedures are rewarded with prestige to match their contribution then we'll see consistently improved documentation.

(And don't even get me started about the parallels to user interface design. At least you don't hear people saying they don't want to "lower" Linux by having it well-documented.)

Suggestion...

[Gerv]

The front page should have three or four words of explanation for the different doc types, e.g.:

Guides - longer, more in depth books
HOWTOS - subject-specific help
FAQs - Frequently Asked Questions
man pages - Help on individual commands
Linux Gazette - on-line magazine

Gerv

Re:Why no easy solution RE:Software level & Doc le

[elflord]

GLIBC upgrading ? -- Forget it ! LDP to the rescue ? -- Forget it ! WHY ? -- COMMERCIAL INTEREST.

Wrong, buddy. Upgrading glibc is plain difficult, because it requires upgrading everything that links to it which is basically every dynamically linked program on your system. The only sensible way to "upgrade" is leave your old libc there and run a hybrid install, but this is difficult, and has a lot of technical difficulties, none of which are Redhat's fault.

If RatHead would make it easy, there would be an RPM to upgrade your libc.

THere is. It's called glibc. The problem is that you also need to upgrade every single application at the same time to a version that is built against the new upgraded glibc.

If you compile all the applications in a distribution in a way that they need the libc at runtime, you would have to recompile every app you use.

Exactly.

and YES, it IS the best way to handle programs, but it's also the best way to force someone to reinstall everything again (read: BUY AGAIN).

Get a grip, buddy. Linux is free ! And CDs are available for next to nothing. Hell, you can probably get someone in your Linux users group to burn you one. My group are always giving out CDs.

SOLUTION: Let the customer who buys a distribution decide whether to trade upgradabiltiy (nice word, hey?) for small apps, with better, overall performance (unless RAM is not an issue and your CPU is fast enough). Let him have the choice to have bigger programs (not dynamically linked) and the chance to upgrade the ESSENTIAL libc. I don't see this happen in my lifetime.

There is little demand for apps statically linked to libc , because most users don't want to load one copy of libc for each process on their system. I have 55 processes running right now. My libc is 4MB. Do the math -- most users don't have this much RAM to burn.

Re:Why categorization by filetype?

[LetterJ]

Again, my objection is not to file format coherency altogether, but placing it as the first factor of organization. O'Reilly's Nutshell books are all the same size, shape etc, not because the authors liked that format, but because O'Reilly decided that all of the books that had the same style, organizational content, etc. should also be in the same physical format. The LDP is saying nothing about what the content difference would be between a HOWTO and a GUIDE. It'd be the same thing as saying that just because you make an O'Reilly book the same size, shape and appearance as a Nutshell book that it belongs in that series. While it would be a problem for the Nutshell books to all be different sizes etc. it would be a bigger problem if there was no consistency in the content. I'd rather that all books published by O'Reilly with "Nutshell" in the title have the same no nonsense approach to the material (not some trying to do a Learn in 24 hours thing with others trying to do a Desktop Reference thing) than that we classify all books of the same appearance, font style, publishing template as part of a series.

LetterJ

Re:MSDN for Linux

[sklein]

If there was a set I'd be willing to pay a pretty penny for it.

But would you work on producing it? That's what has brought us this far, and judging from commercial efforts, it's the only thing that will take us further.

But, on a more immediate subject, do you know know about the -K (that's a capital) switch for man? See man(1) (type 'man man') for more information. Of course, it won't help much with GNU projects, but...

(Yes, i should quote from man(1) but i want people to actually look at it.)

cheers,
sklein

Re:Big and thick.

[schporto]

Well I'll vote for the CD dist. I did have a problem where my modem was not working. Had problems with PNP stuff. Had to shutdown, reboot to m$, go online, read HowTo's, jot down ideas, reboot to linux, try ideas, repeat as nessecary. Now I should mention that part of the problem was I did not realize the install I had done included the howto's with it. I found those eventually and stopped the rebooting part. Which kinda proves the point that I like having local copies of some stuff.
-cpd

Re:MSDN for Linux

[Duxup]

I wouldn't mind working on it. Obviously not the whole thing, and I don't think I have the knowledge to really organize anything like that. However I'd be pretty interested in helping if there was an org doing that.

As for the keyword search your describing, oh yeah, I know of it, I live and swear by and at it sometimes. :-)

Re:One suggestion was unfortunately ingnored...

[elflord]

I didn't say anything about "too stupid". My point is that it doesn't take very much effort to write a HOWTO ( or rather, the real effort is in writing content, not learning the markup language as you suggest. I should know -- I have written a HOWTO ). The intelligence requirements are not just "low", they are as low as they could be. There are GUI authoring tools, and there's a simple markup language one can use by hand. I don't see how you propose to make it easier. As I said, read the (short) HOWTO-HOWTO, or just use Lyx, and you'll be up and running.

BTW, they are not "crying" for authors, and they are not so desperate for authors that they are willing to accomodate to laziness. As much as making it easy is good, you have to understand that HOWTOs don't write themselves, it does actually involve some effort on the part of the author. I'll say it again, the technical skills requirements for writing HOWTOs are minimal. The real work is in writing the content.

And you didn't answer my question -- what format do you propose as an alternative to Linuxdoc ?

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 [linuxdoc.org] 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 [cmdrtaco.net] 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: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.

Nice centralized site

[JDax]

The LDP is a great project and a great site. &nbsp Although most if not all distros allow you to install the HOW-TOs on your box, many of us are low on hd space and would prefer the central location. &nbsp Also it's good to see that alot of the HOW-TOs have been updated to reflect the latest kernels, etc., plus they offer .pdfs.

Good job!

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.

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.

--

Big and thick.

[Evangelion]

To quote a Slashdotter, "Honestly, how many users want to read documentation? How many of them see a fat manual and feel happy?"

Am I the only one that falls into that category?

Excessive documentation turns me on.

Re:MSDN for Linux

[Duxup]

I feel your pain. MSDN and Technet are pretty darned good. Unlike the net you do "usually" get an answer rather than find that other people also had the same problem or question. I'd kill for a Linux style CD-ROM or website like that.
I can barley imagine the ordeal it would take to organize something like that for Linux, however some days I'd kill for one. If there was a set I'd be willing to pay a pretty penny for it.

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.

Re:MSDN for Linux

[GrenDel Fuego]

MSDN is the Microsoft Developer Network. A linux comparison wouldn't really go to newbies who can't connect their box to the next. It would go more to developers. possibly CDs full of the newest IDEs or programming tools.

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.

According to nmap, its Solaris

[salahx]

nmap -sS -O -p 80 -v www.linuxdoc.org

Starting nmap V. 2.3BETA14 by [e-mail] ( www.insecure.org/nmap/ )

(..snip, snip ..)

Remote OS guesses: Solaris 2.6 - 2.7, Solaris 7

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 [docbook.org].

Re:Suggestion...

[LetterJ]

Exactly. See my related points elsewhere on this article.

The only problem with that is that the LDP hasn't decided exactly what each type actually is. According to the article, the difference between a Guide and a HOWTO isn't what's in them, it's the file format.

LetterJ

LDP runs on Solaris?

[hugehugh]

According to Netcraf t [http], linuxdoc.org runs on a solaris box. "www.linuxdoc.org is running Apache/1.3.4 (Unix) PHP/3.0.6 mod_perl/1.17 on Solaris" Can somebody confirm or deny this? Huge

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

Re:Categorization by filetype?

[LetterJ]

I think part of my main point was missed here. Extensible file formats are a good idea. I never denied that fact. My objection is placing the file format as the first filter in content description. The LDP is approaching it from a writer/developer perspective rather than a user perspective. The user doesn't inventory their viewing tools and say, "I've got Adobe Acrobat and a web browser, now what shall I learn today?" They say, I've got a question on how to do something or I don't understand the concepts behind this, where do I find the information. Clear categorization based on the content contained in those documents is more important for that type of approach. Conceptual documents should be structured and titled alike, and likewise for procedural documents.

In all of the good tech writing projects I've been on, content structure and how to group and title the information was more important than the tool. The tool/file format WAS a consideration, but after the content questions were asked and answered. Then the issues of extensibility, maintainability etc. were addressed with the ultimate tool choice coming from those issues.

Basically, I'd rather know that there will be an Introduction in all text files, HTML, PDF, etc. than know that with Ghostscript, I'll be able to read everything. My goal is finding information.

Basically, I feel that regardless of file format, a HOWTO should be a HOWTO. True, if they are all in the abstracted universal file format, they can be converted to all of the other formats and will be more maintainable, but if it isn't in those formats, it's still a HOWTO.

LetterJ

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 [linuxdoc.org]:

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 [linuxdoc.org]:

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/ [lyx.org]