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/
I don't. Before I give a longer answer however I should maybe inform you that in my pro life I am developing XML tools. I have more than enough SGML-light in my day work, I can't see it any more in my spare time! When I take the role of a tech. writer, I am not supposed to do document conversion. In the chain of producing documentation, there is a clear separtion between content provisioning and publishing.
If the LDP and other organisations complain about the lack of documentation they should think about making it more easy to contribute. Why the f*ck does a documentation author have to be an expert in SGML processing, format conversion and other tricks?
Instead of complaining, why the f*ck don't they set up a conversion service, and accept contributions in a number of formats? Instead, they are proud in beeing able to generate the most useless formats out of their SGML markup graves.
Seriously, read the HOWTO-howto ( if you're too lazy to do that, you're probably too lazy to maintain a HOWTO ).
I did, you asshole. I offered my stuff anyhow, stating that I have more interesting things to do in my spare time than writing markup. All I got was responses like yours, trying to imply that I am too stupid/too lazy to do the job. Fine with me, one pice of documentation less for the LDP. Not my problem. I know how the stuff work, I don't need documentation for sed. But then please stop complaining about the lack of documentation writers! As long as it is made difficult, the LDP has not right at all to complain. Period. Instead of working with the authors they work against them, religiously sticking to their SGML. The fact that I can do SGML + their f*cking DTD doesn't mean that I want to do it. The fact that many good authors are just not able to handle the stuff means the loss of potential authors. And all they do is complaining.
Also the LDP is generally approachable, you can join in on the ldp-discuss list, or perhaps first peruse the archive and make your suggestions. Even simpler is the automated feature where you can submit your own links
Personally I feel the plain ascii format is still very useful and it will be with us for the forseeable future. 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. Then all you have is a README.txt and endless files that noone can read anymore. This could probbaly be worth a separate topic.
Just look at the newsgroups, like comp.text, comp.text.sgml, comp.text.tex, comp.text.xml and the rest of it and you too might get the impression that SGML is a good idea that the steam went out of.
Having said that the old DTD used by LDP does the job reasonably well, though some improvements would do nicely.
The issue of graphics is a tricky one. GIF has legal problems, JPEG is suited to photos rather then diagrams, and PNG is not common enough. Worse, many of the users do not have capabilit for fancy graphics. This has come up in the past on the mailing lists.
In the mean time we can use ascii graphics... Later I hope that Scalable Vector Graphics, and CGMOpen will provide a better platform for diagrams.
With LDP and OSWG you have a choice, if you use LinuxDoc you can submit your work to LDP, for DocBook you will find OSWG will welcome your work. Don't let the format issue stop you from writing useful docs.
There is some hope that OSWG HOWTOs can be bundled with LDP docs in the future. Files on disk are in /usr/doc/HOWTO/ , not in /usr/doc/LDP/ so noone is making claims on anyone elses work.
If you have a non-Intel platform and find Intel-isms, why not contact the authors directly?
I feel that the LDP should include various form of slashdot trolls and such. I also advocate the including of jigglypuff since she stops war, famine, disease, and pestilence.
...x3):=
.... ?):=
... . ...`:=
..... ......:=
.. ..=
.._;:.|
:|x%;.-
.. :---..
:==:.... :
...|
..==. ...:|
..:...::|=
xx>+|]]xx]]]]]]]~:]]
]]-a_:~||-+-~++:x)|]
=|:3Oo -...
|=:3%`....
|]:7`..
x+;:.
]]|..........
]|:...|;....
]|:..x%c|:..
=;:..]%%%;...:%%%|..
=;-..:+%+.....?]>:..
;;:..-:::.
=;:....-.
::.........==:.
:=::.. .
|=+:.......::....::|
|]]|;....
]]+]|::.........:=+]
|+]+|::,:.....::|]]]
]|x]::.::;||;:::-|x]
+]]=::;|x]xx]]+]]x%x
Jig-a-le-puff, Jig-a-leeeee-eeee-eee-puff, Jig-a-leeeee-puff-jigaleee, jig-a-lee-jig-a-lee-jig-a-lee-puff
I feel that the LDP should include various form of slashdot trolls and such. I also advocate the including of jigglypuff since she stops war, famine, disease, and pestilence. xx>+|]]xx]]]]]]]~:]] ...x3):= .... ?):= ... . ...`:= ..... ......:= .. ..= .._;:.| :|x%;.-
;;:..-:::. .. :---.. :==:.... :
::.........==:. ...|
:=::.. . ..==. ...:| ..:...::|=
]]-a_:~||-+-~++:x)|]
=|:3Oo -...
|=:3%`....
|]:7`..
x+;:.
]]|..........
]|:...|;....
]|:..x%c|:..
=;:..]%%%;...:%%%|..
=;-..:+%+.....?]>:..
=;:....-.
|=+:.......::....::|
|]]|;....
]]+]|::.........:=+]
|+]+|::,:.....::|]]]
]|x]::.::;||;:::-|x]
+]]=::;|x]xx]]+]]x%x
Jig-a-le-puff, Jig-a-leeeee-eeee-eee-puff, Jig-a-leeeee-puff-jigaleee, jig-a-lee-jig-a-lee-jig-a-lee-puff
Brad,
You were great in Fight Club! Don't listen to what anyone tells you!! You dumb turd. Get over here, you, and give me a hug!
Documentation is the secret to a succesful Socialist revolution. The LDP will become more popular by including our socialist pamphlets in their database. This will allow us to destroy the evil capitalists of the world!!! Then we can be like what Cuba would be like without the totalitarian element!!!
come on in and feel the love! :)
and socialists love jesus, too! :)
Completely Agreed! Linuxdoc is inferior! It is sgml that is based on format instead of content. That is no better than html and we know how much html sucks. Until they get their docs into DocBook like they 'announced' so long ago - they will never be able to take advantage of the real benefits of the technology(SGML) ... things like better searching (element based) and documentation easliy created for the blind and deaf. This is nothing more than an announcement of some guy redesigning the web page - they still haven't done anything since the *last* announcement!
It's HGDP!
Hot Grits Documentation
Project -- it's EL1TE!!!
the site looks like shit, i'm going to make my own LDP site.
Just wondering are you a bunch of lesbians?
Use HGML:
The Hot Grits Markup Language
Or else you are LAME!!!!!!
"I feel RAID is one of the most powerful yet underutilised features of linux. "
Yeah, software RAID rocks!
You dumb shit.
c'mere, you, and I'lll raid ya.
No matter how small it was, it was still bigger than your pee pee.
Q: Should I pour hot grits down my pants?
A: Yes.
Q: How should I prepare the grits before pouring?
A: Heat them. Consult the package directions - some brands of grits may vary.
Q: How hot should the grits be?
A: Warm and invigorating, but not scalding.
Q: What kinds of pants should I pour hot grits down?
A: Most any. Jeans, chinos, and cotton slacks are recommended. Spandex bike pants are best used only by advanced practitioners.
Q: Should I think about Natalie Portman while pouring hot grits down my pants?
A: Only if you don't mind the fact that she was in that god-awful Star Wars Episode 1.
Q: Should I think about Brittney Spears while pouring hot grits down my pants?
A: Absolutely! Brittney Spears appeared to me as an angel in a dream and dictated this FAQ to me. For extra Brittney Spears Grits Karma, you should listen to an MP3 of "Baby One More Time" while pouring the hot grits down your pants.
Q: Does Jon Katz ever pour hot grits down his pants?
A: No. He only writes long, vague, ultimately pointless essays about the subject.
Q: Does Richard Stallman ever pour hot grits down his pants?
A: Richard Stallman has more hot grits down his pants AT THIS MOMENT than most people manage in their entire lives.
Q: How should I clean the grits stains from my pants?
A: You shouldn't. Chicks dig grits-stained pants.
Shouldn't you be at school?
while you are busy restructuring your lasser disk player, please restructure your pants to accept large quantities of hot grits that you will pour down them. thank you.
Alright. Can anyone read the first few pages of the Linux-PostgreSQL HowTo without bursting into laughter? This actually scared me away from PostgreSQL for some time: I was looking for an SQL database server, and found some bizaare document that looks like something "The Tick" would write. Anyone planning on either rewriting this thing or getting the author some medication?
I was just reading the Cable modem mini howto, and it seemed like every problem they gave a solution for recommended booting into windows to solve it, or not explicitly stating that but ("Just go to Settings/control Panel/Networking")
Is this the only How-To that makes it look like you need a crutch installed on your linux box, or are there others.
IMHO, this is a blight on the documentation, as it would give any new reader the idea that they will always need windows on their machine to debug linux.
I feel that the Linux Documentation Project is wonderful. But it needs some things that *all* documentation in the world needs:
Pictures, Diagrams, Illustrations
To More Explicitly Elicit the Contributions of Readers and Illustrators
The first is something that coders in particular like to avoid. I do not know why, but for some reason, coders seem to hate pictures. Perhaps it is because high-speed bandwidth input [to a computer] requires the use of text/keyboard, and not the manipulation of a mouse. Coders should remember that high-speed output [to the human] requires the use of pictures.
The inclusion of pictures in the LDP would make the documents both shorter, and clearer. See "the Illustrated TCP/IP", and the books "Who is Fourier?", "What is DNA?" [both Japanese] for good examples.
Second, I personally feel awkward about replying to the authors when I think of something that needs to be changed in an LDP project. However, I have no aversion to modifying a GPL'ed program and mailing back changes, I've done it several times.
The LDP should try to figure out, "Why is this?" and, "What can we do to fix this?" Personally, I think it is because I think, "Oh God, I don't want to have to learn all about those nasty formatting languages" or whatever. There is also a feeling of more criticism in changing a document (someone's explanation), rather than a piece of code (something someone just hacked together). There have been MANY instances where I have thought, "The author should have done xyz instead. Shorter and clearer." Perhaps this is only my own personal failing, but by the sound of it, others are suffering from it as well.
In the future, we should have DB-backed web sites with the documentation on it, and peoples commentary on each paragraph to the side of it. That way, we could instantly update a document, no effort whatsoever. I believe the results would be explosive. We would also have to be able to upload pictures [jpeg, png] to the web site. [Mmm... Philip Greenspun...]
Finally, we ALL need to make a real effort to get our artist friends into the whole Free Software/OpenSource share-your-code-and-images thing. I have met several artists, quite willing (after I explained) to contribute, they just had no idea how to, or even what the technologies involved where. This extends both to documentation and to the programs we produce.
Thank you for your time. If you would like to futhur discuss this with me [I want to set up the aformentioned DB], mail lion@speakeasy.org.
Take care, Lion {:)}=
One of these days I'll get YET ANOTHER Slashdot account, and write the password on all 4 walls of my room.
I can't wait until Feburary. APPLE RULEZ!! LINUX SUXXX!!!!! I'd like ya to hear that.
The news is that there is a search box; LinuxDoc wasn't always searchable. The news is not that it was moved from elsewhere, as far as I know it was at the front page since it was made available.
What I find suspicious is that so far noone has been able to substantiate these claims, giving any examples, certainly no good examples.
Until then I will regard statements like the one above as resulyts of near-religious experiences brought about by alien abductions.
Oh yes, seen the DocBook """manual"""? Eric Raymond found it useless and I must admit I am suspicious of a docs product that seemingly is uanble to be used to properly document its own use.
Finally, LDP is about making contents, can anyone tell me how contents is held back by format? News uses mostly plain ascii and it works for me. If you cannot express yourself without the use of tags, bold faces, italics etc then you need to look at the problem closer. Preferrably with a mirror.
Still, you do not have to do the conversion yourself, the simplest way is just to announce the plain text version on some web site, ask for help for conversion and someone might just do that. Once the conversionis done you just follow the layout, that is much simpler. that way it is simple for you and simple for LDP and handy for te ned user who can read your document in any format that best suits their needs.
So why not try it?
Isn't it interesting how underrated my funny comment is ?
Not only does poor Linux documentation drive book sales, but it seems that the revenue model for Linux involves giving away the software and making a living selling support.
That translates into: The worse the documentation is, the more money to be made.
It would explain "the tragedy of the commons" (with Linux documentation defined as 'the commons.') Nobody's writing good free documentation for Linux, because doing so destroys the "profit center" many people have had to resort to for paying their rent.
Richard Stallman spoke out against the commercialisation of support for Free Software (specifically addressing the O'Reilly books) awhile back.
You know, the copyrights involved allows you to do just that. Lets us see what you can come up with.
The main switch that was done was to require also mini-HOWTOs to be written in Linuxdoc SGML. earlier a mini-HOWTO could be written in anything from plain ascii to HTML.
Consider the smoke cleared and feel free to join in with the contributions you feel you wish to make.
I don't agree with you. Your idea of automated HOWTO's in the form of a script would be impossible to maintain and would remove all the choices people have.
If you were perfectly correct in this, then SUSE would be by far the best Distro Ever since they do everything for you. And if you want to do something different - it's a fight between you and YAST.
One reason that I never contributed to the LDP was that they kept changing the tools used to produce the documents. That is not so bad on the face of it. The bad part is they would make these pompous announcements -- "Don't use linuxdoc anymore use docbook" or some such thing. Yet the software they wanted to switch to was buggy and NEVER FINISHED. Top it off with the fact that the dude who had been bossing people around and telling them what to do just WALKED AWAY and left his mess for others to clean up. After years of bullshit, the much touted do everything software documentation package was abandonned without a maintainer. Shit.
Stallman has got to be stopped, otherwise the open source movement will stop dead in it's tracks.
I just sent my M$-obssessed boss five printed guides taken from LDP along with a Linux CD and a boot floppy. Now he can't say 'Linux is undocumented' anymore.
Let's hope this keeps him from buying any more NT trashcans...
Aaron,
Your daughter was GREAT in 90210. Don't listen to what anyone tells you! Keep believin'!
Get over here, you dumb turd you!
Glenn,
You were GREAT in Fatal Attraction! Don't listen to what anyone tells you! Have faith!
You dumb turd, get over here and give me a hug, you.
Slashdot wastes 100k dollars on "beanie" award when they should have been using the money to hire some alt.2600 hitmen to take out the spammers. The job title is ``security consultant''.
Pretty?! What do you need PRETTY pictures for? All we need are effective pictures.
Don't get me wrong, I'm glad that the LDP finally figured out that nobody could find the search interface, but does moving the search box really deserve an announcement on /.?
Is today just a really slow day or is someone calling in favors?
halo, don't knowbuddy say the y word. didn't happen like day say. don't furget 2 ad ur 2sense in duh effort to how2, b4 the acquisition of same buy the billyunheir megasloth wannabee FUDlickcysts.
New Troll Grits (tm)
1500hrs 8/2/2000
Slashdot user lm563872bs today revealed the new food sensation that is sweeping geekdom.
Troll Grits, a genetically modified form of vegetable protien, shaped into the likenesses of geek Goddess Natalie Portman and UberGeek Linus Torvalds are entirely flavourless and designed expressly for pouring down one's trousers an an inopportune moment.
Nobody whatsoever was available for comment.
Troc
Troc's dubious podcast and blog: http://www.trocnet.net
The B.A.R.R Pount - Back for the Oh Oh
You're back now at the jack-off hour this is DJ Roblimo
on w-balls, right now, something new, by Thew Barry Barr
and this one goes out to all the ladies from all the guys
a big bow wow wow, cuz we gonna make it a little mystery
here tonightm this is dj roblimo, on the website that slaps you accross your fat ass, with a fat dick.
when i met you last night baby
before you opened up your gap
i had respect for ya lady
but now i take it all back
cuz you gave me all your pussy
and ya even licked my balls
leave your url on the cabinet
and i promise baby, i'll give ya a call
next time i'm feeling kinda horny
you can come over, and i'll break you off
and if you can't fuck that day baby
just lay back and open your moth
cuz i have never
met a girl
that i love
in the whole wide world
well, if CmdrTaco gave a fuck about a bitch i'd always be broke
i'd never have no motherfuckin code to barr
i gets loced and looneym bitch you can't do me
do we like bsd, you hoochie groupie?
i have no love for hoes
that's something i learned in the pount
so how the fuck am i supposed
to pay this hoe, just to lay this hoe
i know the pussys mine, i'ma fuck a couple more times
And then I'm through with it, there's nothing else to do with it
Pass it to the homie, now you hit it
Cuz she ain't nuthin but a bitch to me
And ya'll know, that bitches ain't shit to me
I gives a fuck, why don't y'all pay attention
Approach it with a different proposition, I'm CmdrTaco
Hoe you'll never be my only one, trick ass biitch
Guess who back in the motherfuckin house
With a fat dick for your motherfuckin mouth
Hoes recognize, niggaz do too
Cuz when bitches get skanless and pull a voodoo
What you gon do? You really don't know
So I'd advise you not to trust that hoe
Silly of me to fall in love with a bitch
Knowin damn well, I'm too caught up with my grip
Now as the sun rotates and slashdot grows bigger
How many bitches wanna fuck this nigga named CoyBoyNeal, I'm all the above
I'm too swift on my toes to get caught up with you hoes
But see, it ain't no fun, if my homies can't get a taste of it
Cuz you know i don't love um
Whoa!
Hey, now ya know, inhale, exhale with my flow
1 for the money, 2 for the bitches
3 to get ready, and 4 to hit the switches
In my Chevy, six-fo' Rad to be exact
With bitches on my side, and bitches on back
So back up bitch cuz i'm strugglin, just get
off your knees and then start jugglin
these motherfuckin nuts in your mouth
It's me, Roblimo the nigga with the clout
Whoo!
The B.A.R.R Pount - Back for the Oh Oh
The B.A.R.R Pount - Back for the Oh Oh
Hmm, nice web site "relaunch" :-).
But they still haven't solved a fundamental problem: The LDP as well as e.g. the FSF cry and cry for people writing documentation. Fine. But why the hell do they make it so difficult to contribute? Still the LDP requires SGML for documents. 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.
And what is their "right" to insist on SGML anyhow? I mean, some people advocate the open-source idea as a gift culture, but people like the one in the LDP claim to have the right to insist on how ones gift has to look like...
> Documentation is something most coders hate
I don't necessarily think that this is true. As Eric Raymond points out in his How To Be A Hacker FAQ, almost all good hackers and are also adept at mangling words.
I tend to write documentation as I go along because it helps clear my thoughts -- if I can't clearly and concicely write what I'm doing then my algorithm just isn't very good.
Further, I tend to find that small programs have *more* documentation than big ones. I think the problem is in managing change to text files. It's just not as easy as updating code.
I guess what we are failing to realise is that Slashdot is a humourless repository of knowledge, designed to objectively portray the world of computing and Linux etc without any bias or emotion whatsoever.
Troc
PS for Americans - the above was a sarcastic message
Troc's dubious podcast and blog: http://www.trocnet.net
Ok, moderation is really annoying me now. The post I made wasn't a troll! It was an attempt at humour. If anything it could have been moderated as offtopic, but what was trollish about it?
:)
Was I desperately waiting to start a flame war about AMD vs Intel? MacOS vs the world? Bud vs Bud light?
No. Some people should lighten up
Hohum.
I'll await the 'troll' score for this one I suppose.
troc
Troc's dubious podcast and blog: http://www.trocnet.net
Yeah - RedHat has a pretty good HOWTO list and also links to the LDP (in fact they put a link to it on your desktop when you install)
Very useful unless you are trying to get ethernet working via pcmcia and the pcmcia HOWTO is on the 'net and you aren't..........
I burned a cd with all the HOWTOs on it in HTML with a couple of navigation pages and a search engine I knocked up recently and I've found it extremely helpful when on the road etc.....
Troc
Troc's dubious podcast and blog: http://www.trocnet.net
Thanks for doing a great job.
** Martin
The Mac is much closer to being an "appliance" than anything x86 based. Part of the reason Macs are so easy to use is because they have a much smaller hardware base. Mac software doesn't have to worry about half a billion different motherboards, video cards, and sound cards. Mac server software also tend to take a more focussed approach. With Linux the approach is software that can be configured to do just about anything you please on just about any hardware you can imagine (with the exception of some hardware that doesn't have specifications available).
That's not to say that the Linux approach is better or worse than the Mac. It's just that the Mac reaches its solutions by narrowing the problem space.
If you're willing to spend the money, companies like VA Linux will simplify the problem for you. They worry about all the variables (just like Apple does) and offer you a machine that just works. If you can do without complex software like sendmail and Apache, you can get simpler, less configurable software that performs the same basic tasks (just like on a Mac).
The Linux Knowledge Base Project
We (I'm one of the core developers) went live today.
They are nopt trying to discourage use, they are simply not encouraging newbies to try compiling their stuff. I don't think that's such a bad idea. If the user can't work out how to compile ( there are plenty of docs that explain how ), they probably shouldn't.
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.
I'm sure this would be a wholly impossible and unpopular, but perhaps maybe kernel releases should be held back pending completion of documentation. The 2.2 upgrade was kind of frustrating because a lot of what was broken by the upgrade was so poorly documented (don't get me started on finding the current sources for util-linux and so on).
There should really be some core documentation about building and installing the kernel that stays in lockstep with the kernel itself, along with generous notation about ancillary packages broken by upgrades.
It's insanity like this that makes BSD look kind of appealing.
However, until recently, the tools haven't been there. Sure, we have GIMP for pixel editing, but nothing comparable for diagram use -- nothing like Visio or Illustrator that lets you reuse components, make connections, output to a variety of formats, have a generally nice UI, etc.. (Xfig doesn't count, though it's better than nothing.)
However, there's a lot of promising work in this area; there are several open-source projects (Dia [my favorite], Sketch, KIllustrator, Gill, etc.) hoping to remedy the problem. Even more importantly, the SVG standard from the W3C offers the promise of a common data format for interchange between these products -- and a common data format is vital to something like the LDP.
The Open Source Writer's Group only has docbook. This means two divergent resources for documentation.
Linuxdoc has been officially supplanted by docbook in the community by most authoritative sources. Why hasn't the LDP started accepting docbook HOWTO's?
I don't mind writing docs, and I love being able to help out those who are looking for answers, but that fact that the most recognized resource for getting information is not staying up to date with the community is utterly frustrating.
Excuse the rant, just a frustrated docs author.
Arrogance is Confidence which lacks integrity. -- me
While the new site looks great, the tables don't scale to various window sizes/resolutions, so you have to scroll horizontally.
"Oppression and harassment is a small price to pay to live in the land of the free." -- Montgomery Burns.
... is the issue of these .......s who spam slashdot lately.
Status: Moderator have five points, spammers got a lot of time.
Proposals:
a) Let moderators moderate as many posts *down* as they fancy
b) If an anonymous post got two (or three) negative markings and no positive ones it should be removed
c) A squad of certain nature should be organised and deployed
Oh I get it now. Poor linux documentation = increased O'reilley book sales!
(Shrug) I've lost all faith in the intelligence of moderators since the time I posted a humorous reply to a troll. I had disabled the karma bonus but some dumb ass moderator marked it as "flamebait". So I got pissed and posted two messages swearing up a storm at moderators, I kept the +1 bonus for both messages and the content could be boiled down to "fuck you moderators". Neither was moderated down from a two score. Bloody worthless if you ask me.
--GnrcMan--
I agree with what you're saying, but I don't see any clear solution - the newbie should either print the page out first, or go get an O'reilley book. Or use a friend's computer.
Well, if you don't have internet access, you have to get the documentation somehow. One such way is by purchasing printed matter (O'reilley book) or generating your own (printing). Alternatively, you could save the material on your hard drive. And I believe red hat includes the then-current HOWTOs and other LDP stuff in their distro, although a poster further down pointed out that this is not always the case.
As a language slut, I've been around the block a few times and never really cared the company I kept, from M68000 to Ada, from Eiffel to C, I've been used and abused by the lot.
Then one day I started Java, I'm used to being on projects where sometimes the comments are the only documentation so I've become a fairly verbose commenter of code. And in Java it suddenly had a point. javadoc a tool that goes through the files, documents all of the APIs and turns them into a professional looking web site.
Having looked at some of the Linux code there are quite a few cases where this would produce pretty good docs right now, and it would encorage people to comment more in future.
An Eye for an Eye will make the whole world blind - Gandhi
There is a site, GetTux.com, that offers a monthly subscription of HowTo documents, specially formatted, and with a keyword searchable index. Kinda cool to not have to login to the net everytime something breaks...and if your pc is down, well, ya probably arent getting online anyway. :-)
It looks like a good idea, and their website implies that they may have some new ideas about how to do Linux docs...
"Don't try to confuse the issue with half truths and gorilla dust."
Bill McNeal (Phil Hartman)
Eh, don't worry about it. I got moderated to +5 Funny for a serious post once. I made the mistake of being critical of linux ;-)
;-)
Of course I AM a full-time troll, so . . . .
Bad things often happen to good people,
It is up to them to see that they remain good.
Anyone who has done much with Windows knows the feeling of fighting the system. You have a very good idea of what you want to do, but Windows has a different idea, so you spend all of your time trying to trick it into doing what you want.
An example: Installing a harddrive in Windows NT is normally fairly easy. Recently, (because of cheap harddrives at CostCo) I ended up replacing my boot drives both at home and at work. It took me three hours to do my home Linux box (and only that long because I quite frankly didn't know what I was doing. I only got around to reading the HowTO 2 hours in.) It took me almost two days to get the Windows drive replaced. Why? Because Windows "knew" what I wanted, and kept screwing things up. For example, it "knew" that the new drive was "E" and that it should change shortcuts to anything I copied there accordingly. This, of course, caused major problems when "E" because "C" and the original "C" went away. (The machine became unbootable as all the drivers were on "missing".)
Anyway, I won't bore you with the details, but in general, Linux really is easier, if you know what you are doing, and are not doing things in a particularly formulaic way. Windows is generally easier for newbies not so much in that it has nice, pretty graphical dialogs, but in that it simply steers them towards doing things a certain way. This is great until they learn enough to try something interesting.
The cake is a pie
"Extrans (html tags to text)" is broken, but full HTML seems to work still. This seemed to happen around the time that that HTML security warning showed up...
A pain, because I hate having to remember all those paragraph tags.
The cake is a pie
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.
I see a place for Literate Programming in Open Source, which is underused IMHO. If you the coders expressed what a program did in a sort of human readable language, we the lesser but sometimes more eloquent multiplicators might have a chance to see what the code does without having a deeply rooted idea of the programming language used, so we could write explanations how to get the code working for someone else (ie manuals).
While I am meta-moderating the "off-topic" moderation on this "Fair", I must say that I really found it hilarious, and that the person who wrote it is brilliant.
"Don't mind me cutting myself on Occam's Razor"
There is a very good reason that the profession of
Technical Writing exists. IMHO there would be marked & rapid
in the clarity of DOC's if a couple were sic'ed on to the
LDP. Changes could be referred backo the HOWTO's
original authors to check for factual accuracy. I expect
that most Howto authors would see it as taking a load off,
rather than taking it as an affront (I don't know any IRL though)
It would be great if somone like VA or RH would front
with the $$$ for this (& what a way to endear yourself
to the community). I guess the only prob with this idea is
that the LDP has to be seen as independant.....
Full plate and packing steel! -Minsc
I think Linux could do with something like Microsoft's MSDN or Knowledge base CDs. Althought there are a few good web sites around that give this kind of information they are not as convenent as having the whole lot on a CD. I would see this a something that could be mass produced and dropped in the box with any distribution. By using (HT/X)ML and a Java search engine (like some of the books on CD) it sould be easy to find information quikly. In the Microsoft world, CDs like this have made a lot of tasks easier and the same could be applied to Linux.
Go look it up in a dictionary.
Aside from the fact there is not even a glimmer of indication that RMS and the FSF will try or indeed wish to assume the honour for the work of the LDP, there is also the fact that the FSF has spent substantial resources on manuals and documentation. Take, for instance, RMS' offer of some time ago to pay a goodly-sized amount of cash for a good, free manual for GTK/GNOME programming.
I have no doubt that this will do for Linux documentation what Freshmeat has done for Linux software. By announcing these as they come out, we'll also be able to keep everyone updated. Kudos to the LDP!
In retrospect, the LDP would have been an excellent nomination for a beanie for best Linux advocate! Hindsight's 20/20, I guess!
Brad Johnson
--We are the Music Makers, and we
are the Dreamers of Dreams
Brad Johnson
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?
Any operating system complex enough to accomplish a multitude of tasks (networking, memory management, multitasking, multiprocessing, etc) is too complex for its use to be obvious in all respects. Ditto for an OS with enough flexibility to support the multitude of hardware out there. Simple machines, like toasters, require little support because there are so few options for how to use them. But even copy machines these days have become flexible enough to require LCD help screens instead of just an LED readout showing how many copies you decided to make. Linux may not be easy to use in the way that an appliance is, but neither is any other complex machine.
Think about all the various OS's you've been exposed to. Windows is NOT intuitive, it only becomes easier to use over time because the same shortcuts you learn for one package generally work for others. You need a lot of support for it because of its instability, and even more support if you decide to get mucking around in the device properties. The Mac OS provides a lot of help built into its UI where you don't necessarily see it (large hit zones for example) and also uses the same shortcuts between many apps. Plus it supports less hardware, reducing the required complexity behind the scenes and generally increasing stability, and I believe you don't have the same access to tweak it yourself. That sure cuts down the options the user has to digest and work with. I don't know enough about BeOS to speak for it but I'm sure Be users don't go from newbie to wizard in two weeks' time. Command-line OS's have all the complexity of Windows plus no visual cues of how to begin finding out what to do next: you might know enough to try 'help' and '?', but if you have nothing to click on and you don't know what magic words to use, it becomes like an old text adventure (Hitchhiker's Guide comes to mind) where you type anything you can think of hoping that you'll hit the right command. Your complete newbie who doesn't know 'man' probably won't know how to reach the Linux user community for support either: that pile of how-tos may be the only thing they know how to access.
To return to the point, the fact that an OS requires support is, in a twisted way, a sign of its capabilities. How that support is handled could be a flaw or a benefit, but the need for support itself isn't a sign of a bad product. Unless it needs support because it doesn't do what it's supposed to. Having a pile of documentation isn't in itself a bad thing either: nobody is forcing people to read it, it's there if they want it (and know how to find it).
Jenny
I think my point was missed entirely. The idea that content should be based on how it's formatted is misguided. In the Linuxdoc Manifesto (http://www.linuxdoc.org/manifesto.html) section 2, it points out that the major focus of the LDP is writing Howto's. Howto's are simply words on virtual paper. What I maintain is that the learning curve to sit down, open up your favorite text editor ( whatever ya want to call it ) and type is by far easier than SGML or Docbook. Yes, there are things like the Guides which I think should be done with Docbook/SGML. Afterall they are basically books. I don't think Howto's can be considered books. Hence SGML/Docbook is overkill for them. The mini-howto's dont have to be submitted in SGML. If SGML/Docbook is so great why didn't those authors submit them in those formats? ( hell maybe some did, but not all ).
SGML, Latex and Docbook, in my opinion, are based on typesetting paradigms. I arrive at my opinion from reading about Latex in the latest Linux Journal Issue, Feb 2000 page 116 "LaTex for Secretaries". And from other sources like the Open Source Writers Group website http://www.oswg.org:8080/.
You wrote, "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."
I maintain any publisher or printer who can not easily print or publish plain text isn't worth a grain of salt. Open any html editor and tell me you can't import plain text. Bah! You can. It's got to be the simplest task of them all.
And what does publishing or printing have to do with editing? Isn't that the responsibility of the writer? Or perhaps a professional editor. In the context ( and you have to keep it in context ) of LDP Howto's if you edit someone else's work havn't you infact re-wrote it? And if at that time you are changing the order of a few paragraphs and adding a line or two you've simply revised thier document. Check out http://www.linuxdoc.org/COPYRIGHT.html.
You wrote, "Simply put, It's not easy to convert all those HOWTOs, especially from a text format which has no logical structure."
As with any document regardless of format, structure is dependant on the writer. You can just as easily get SGML source that is badly formatted, just as you can get plain text that is beutifully formatted. So your argument about structure is very weak. Conversion from SGML to whatever is no more difficult than conversion from text to whatever. In fact just as easy to convert plain text as anything else.
The argument is really about how easily any document can be produced. I believe plain text is the easiest way to produce any document. It opens up non-technical writers to write. All that is rquired is a text editor or word processor ( I dont know of any that don't do plain text ).
You wrote, "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 ?"
You drive my point home with this statement. If someone wants to read 1 page of the HOWTO-HOWTO and cant quickly do so in plain text isn't really going to benefit from whats written in it.
The effort you spoke of really is in the content itself. I would rather have Joe the Linux User write about his 30 station heterogenous network in plain text ( it's no harder to format plain text than deal with SGML markup ) and format his text as he types. Thats where the real effort is...Content.
I would also like to see Jane the Secretary at Joe's office to write about her adventures using a mixed network of computers. Maybe she came from a Windows background and would like to share her story with secretaries migrating from Office to KOffice or something. I think she would be better suited to plain text than SGML. And I think her writings may benifit others in her situation.
Technical writing is an art I agree. What I suggest is technical writing doesnt mean the writing itself has to be technical. Your worried that someone won't be able to publish or print something and Im worried that we can open up technical writing to include more fresh minds regardless of background. Writers know style and the importance of properly formatted paragraphs, etc. They shouldn't be limited by a file format ( some may, some may not ).
There are plenty of tools for the conversions out there. In the context of the LDP I say submit them in plain text and convert them. You already have to submit them in SGML and they convert them anyway. By submitting the content in the lowest common denominator ( pain text ) you open up the writing pool to include all writers, not just technical writers.
You wrote, "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" ). "
Ahhh....but you already know how to write using plain text? Open application, type content, save file, submit file.
It's not about typesetting anymore. Desktop publishing has generally put that out to pasture. As Unix/Linux moves closer and closer to our desktops why should we revert to 80's mentality. Keep It Simple.....Take a vote! Whats easier, plain text or SGML/Docbook? Get a good cross section of backgrounds to be fair. You'll find text wins.
* On a side note I recall reading somehere in one of the README's of my Linux distribution that programmers generally do not make good writers. Don't you find it ironic that good writers may be limited by SGML/Docbook? Isn't a major complaint about some software that documentation is generally weak or confusing? I'll refer to Linuxconf, on the Linuxconf mailing list a major complaint is lack of documentation. Jacques software could have loads of contributions to help documentation if his software utilized something simple like plain text for the help files. Or at least if his software could parse the text help files somehow. ( maybe thats not a great example, but it's what comes to mind right away ).
Anyway, I've rambled enough. Im not saying SGML/Docbook is bad or has no place. Im simply saying requiring Howto submission in those formats limits the contributed work. A solution is to allow plain text contributions and convert from there.
Respectfully,
Scott
Integrity is what you are when nobody is looking.
I think it's great SGML can be converted to the formats you pointed out. However, I think the idea behind the LDP shouldn't be based on "wow, this can be converted to .this or .that.
It should be based on the content, not what type of file format it's available in. While your short list of SGML advantages was presented I think it notable that the sgmltools project has been suspended for quite some time. (http://www.sgmltools.org/suspended.html)
While SGML may not be any harder to learn than HTML it is still a barrier to some. But, I believe theres is a solution right under our noses.
I think LDP documents should be submitted in plain old text. Thats right simple plain old text. It seems to me LDP has it backwards. If Howto's and the like were submitted in plain old text, then everyone regardless of OS could view them. Then if a particular format is preferred it could be converted by the reader. Come on, how many OS's are excluded from viewing plain text? I am making an assumption ( I think a safe assumtion ) that all operating systems have access to something that will read plain text files. I can't think of any word processor or office suite that cant read plain text. Shoot, on my linux machine there is at least 10 different applications that can read and write in plain text.
The added benefit of plain text is that anyone who can type a Howto or a document, that may lend a helping hand to someone else, can do so without trying to figure out SGML or DocBook or XML.
The downside to plain text may be graphics for diagrams. But just as the LDP has "special Howto's" a catagory for those documents could be created. And by far the vast majority of Howto's are nothing more that text.
Respectfully,
MZoom
Integrity is what you are when nobody is looking.
Why doesnt linuxdoc carry the NEW linux raid howto that is distributed with the new raid patches.
After being on the raid mailing list for a year it is plainly obvious that this is one of the biggest sources of confusion new users have.
The raid HOWTO linuxdoc carry is obsolete (like the raid code in the kernel v0.36).
I feel RAID is one of the most powerful yet underutilised features of linux.
The biggest thin preventing it from getting wider use is the confusion amoungst new users.
Apart from this i think linux documentation people do a arvelous job, and i applaud them, but linuxdoc could do its job better if carried the documents users need rather than hanging onto the old obsolete unmaintained ones.
my 2c (sorry if this sounds harsh, im a bit passionate about raid)
Glenn McGrath
"Yes, and? That's The Linux Way, my friend! I honestly don't see what's painful or ugly about it."
:-)
Sorry, I wasn't clear. You had said that if you're not happy/comfortable with the kernel-building docs, then maybe kernel building isn't for you. My two (2!) points were:
(a) Not building a kernel wasn't an option, as I had upgraded my hardware. Doing a complete reinstall would have been the only way around it.
(b) Despite some extensive Unix background, I found that kernel building (and for that matter, getting gcc installed and working--_correctly_) was fairly annoying the first time 'round. The kernel docs are pretty good, but they're definitely not kept current with the kernel releases.
Also, "If things got off the ground..."
Again, I wasn't very clear. Must not have had enough coffee this morning.
I meant if my hypothetical full-blown, next-stage addition to the LDP involving a lot of extra work (editing, reviewing, etc.) were to go forward, I'd definitely be in there, volunteering.
Part of the difference in our viewpoints, I'm sure, is that I came to Linux from the world of commercial Unix products. The Sun documentation (to choose an example) is lovely. Check out their website to find out just how well a documentation project can be done.
"People who do stupid things with hazardous materials often die." -- Jim Davidson on alt.folklore.urban
Since you're addressing this to both of us, I'll answer bits of all of it.
<i>"Both these things are already done. There is a standard format for docs, and unmaintained docs are held in an "unmaintained" section."</i>
True, there is a standard format for docs, but it mostly pertains to the visual layout from what I've seen. Content, editing, and comprehensiveness appear to not be issues.
<i>"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>
Heh, this is true. It's easy to decide What Needs To Be Done, as long as we don't have to implement it.
That said, I'd quite happily be a part-time LDP editor if things got off the ground.
<i>"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."</i>
I have to agree with the other poster; building my first Linux kernel (2.2) was a moderate nightmare, and there was _no_way_around_it_! I added an ethernet card, I had to compile support into the kernel (or build a module--either way). Regardless, it was a painful and ugly process, despite the fact that I've built kernels on HPUX, AIX, Solaris, and SunOS 4.0.2 (ouch!).
"People who do stupid things with hazardous materials often die." -- Jim Davidson on alt.folklore.urban
That should say it all, but, I'll explain further. While it may seem great to just accept anything that anyone writes, it really sucks. If someone submits a HOWTO in MSWord format (why you would do that in Linux, I don't know, but this is just a theoretical debate!) then someone else has to convert the document to a format that is similar to everything else in the LDP document set. By picking a single standard and insisting on it, they prevent having to spend all of their time converting from 50 different formats (LaTeX, .Doc, raw text, HTML, RTF, etc.) to a single format to make them available on the web. Remember, some of the HowTo's are for newbies, so you don't want to complicate maters by requiring them to use 10 different document viewers to find the information they were looking for to get thier system set up the way they want it!
As for having written something in a different format, why not just convert it? I'm sure that SOMEONE SOMEWHERE has to have written an (x) SGML converter. Heck, even if you wrote it in (y), you can probably run it through an (y) to (x) converter, then (x) to SGML. Then do some very minor cleanup (er, at least I would hope it's minor) and submit it.
Is there currently a sed HowTO? If not, well, get off yer duff, and convert it and submit the damned thing!
Davis Ray Sickmon, Jr - looking for something to read? Check out my three free novels at MidnightRyder.org
Linux != Intel
But many HowTos etc. make this assumption. As a long-time Mac user, I am used to having commercial entitities make the assumtion that PCs = wintel boxes, but I had hoped for a more heterodox outlook in the Linux community. We tout the OS as thriving on a multiplicity of hardware configurations, but most of the documentation is written as if Linux box = Wintel box
Do we have to have diverging forks in the LDP?
Should LinuxPPC users set up LDPppc?
I see comments saying the format must be VT100 readable. How about similar standards for content?
There are a lot of good distros out there, I bought SuSE which came with a vast plethora of HowTo's and FAQ's but you never actually know which ones you'll need and its sods law that the one you need will be the one you ain't got :)
;)
Hows about "The Linux Documentation in Public Libraries Project" ??
Ripping an new rectum in the fabric of spacetime.
I know, i have some printed stuff on my desk, It was published recently; but to be honest, on flicking through it seems woefully out of date already :(
Ripping an new rectum in the fabric of spacetime.
What we need now is a really good central-distributed hardware database.
This nonsense of several different hardware databases has got to go.
What I envision is a hardware database that can be accessed from various sites, ie, Linux.com, Redhat.com, debian.org, etc. where updates submitted to any of the sites get automatically distributed to the other sites.
This hardware database would not only include information about whether the hardware works or not, but would include directions on how to make it work, and any needed drivers. The drivers would not be links to locations off-site... I've had too many times when I need something that's listed on freshmeat.net or somewhere, and they don't have the file on-site, and the link is dead. What good does it do you if there is a driver for your hardware, but you can't get it?
If something like this already exists, please let me know... I sure haven't seen it.
Many times, the author wants to follow the philosophy of "Release early, release often". However, they're releasing first-gen software, something that probably works most of the time on THEIR machine. The sparse documentation is there to sort of act as a "you must be at least this tall to go on this ride" meter...they don't want newbies trying to use the package yet, because it's not ready, but they do want experienced coders to be able to look at it, and hopefully help with it.
One example is ext3. It actually comes with very good instructions for using it. However, the instructions tell you simply "patch the kernel", and that if you don't know how to do this, you should stop reading. This is appropriate...you're trusting your filesystem to 0.0.3 software!!
In short, sometimes it's good to discourage less experienced users from using something, because it will probably do more harm to them than good for them.
WMBC freeform/independent online radio.
the GNU/LDP. After all that freak Stallman takes credit for everyone else's work anyway.
I can hear it now, "The documentation of the GNU system was in place, the LDP just provided the missing piece to the the project, the actual text. Therefore, I am usurping the LDP and affixing my GNU prefix to it. I will not speak to you unless you refer to it as I see fit."
no one thought he would try to be an asshole about Linux either now did they.
NEVER underestimate the ego of a egomaniac.
Maintenance is key! I am, at various times, a tech writer/tech editor, and I've been called in to clean up the mess left by sub-par contractors and other "professionals" who simply used whatever tool they liked, without regard to the project history and maintenance cycle.
Document maintenance is a flaming nightmare unless you're very very careful about it. You absolutely MUST pick a standard file format, and stick with it. For the LDP folks, the only choice they had was SGML. It's practically everywhere, it's well-documented, and many of the tools that work with it are free.
If the LDP just accepted any ol' file format you felt like sending, they'd be spending 98% of their time cleaning up after your mess; trying to convert binary formats, trying to rig together transform engines with weirdo hacks to work around inconsistencies in formats . . . these are all things that I've had to do, and it ALWAYS sucks.
Besides which, you know darn well that fully a quarter of all LDP submissions would probably be in some bizarro self-made markup language that the author felt was somehow "better" than SGML, simply because it looked kewl when transformed by his/her own home-built scripting system.
Think of it this way: CPAN only accepts Perl stuff. LDP only accepts SGML stuff. It's the nature of the beast, so to speak.
I have no
Okay, so this only seems to effect the front page, but it was enough to put me off initially.
Easiest way to migrate Windows from one drive/partition to another (short of using special software (such as DriveCopy or the thing that comes with the Maxtor drives), which is what we're talking about, right?) is to boot Windows and either open a DOS box or go to Start|Run, and type (assuming you're copying everything from the C: drive to the D: drive) "xcopy32 c:\*.* d:\ /h /e /c /k /v", if you have xcopy32 (I'm not sure when MS introduced it into Windows). Worked like a charm on my Win98 partition, and took, oh, between 10-30 minutes (can't remember for sure). This was when I moved from a 2 (!) gig drive to my present 27-gig drive.
(Score: 1, Offtopic)
[Moderation Totals: 1 Informative, 1 Offtopic, Total: 2]
--
We have fought the AC's, and they have won.
It seems like getting information on installation/configuration items is pretty good, but getting developer information is still difficult. It seems like with the amount of linux development going on these days it would be a simple thing to find current information on kernel debuggers, device driver development, etc. But from my perspective information is spotty, and dated at best.
I've been doing some Java development and can't help to notice really how good Sun's javadocs are. I don't know about anyone else, but something similar to this would be wonderful for the LDP.
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
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
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!
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.
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