LDP Restructuring and Growing 142
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/
Still SGML is required... (Score:1)
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...
Re:Open source docs (Score:1)
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.
Re:(OT) Moderators (Score:1)
Troc
PS for Americans - the above was a sarcastic message
Re: Meet the Trollers' (Score:1)
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
Re:Well there are ways and ways.... (Score:1)
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
The new site is great. . . (Score:1)
Thanks for doing a great job.
** Martin
Re:Too much help is not helpful (Score:1)
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).
Re:Biggest problems with linux documentation: (Score:1)
The Linux Knowledge Base Project [linuxkb.org]
We (I'm one of the core developers) went live today.
Re:Open source docs (Score:1)
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.
Re:ONE step in the right direction... (Score:1)
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.
I agree, but we need tools... (Score:1)
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.
linuxdoc is dead! Long live docbook! (Score:1)
The Open Source Writer's Group [oswg.org] 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.
Design could be better.. (Score:1)
Re:Linux Documentation Project needs: (Score:1)
Even though I'm all with you on plaintext issue, I have a feeling that VT100-compatibility is less important than PC-compatibility. It scares people. I consider myself pretty "tough" in this issues (and generally I like CLI's - like, say, in SoftICE), but sometimes linux console s/w drives me nuts... (Not to mention emacs
Totally offtopic but needs to be addressed (Score:1)
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
Re:Howto HOWTO! (Score:1)
(OT) Moderators (Score:1)
--GnrcMan--
Re:Howto HOWTO! (Score:1)
Re:Howto HOWTO! (Score:1)
javadoc why not linuxdoc (Score:1)
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.
Documentation CD (Score:1)
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)
Moderation (Score:1)
Of course I AM a full-time troll, so . . . .
Re:automated HOWTOs (Score:1)
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.
Re:Open source docs (Score:1)
"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.
Re:Open source docs (Score:1)
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).
Re: Meet the Trollers' (Score:1)
Insert $$$$$ (Score:1)
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.....
MSDN for Linux (Score:1)
Ad hominem (Score:1)
Foolish RMS-bashing (Score:1)
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.
This is great! (Score:1)
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
The need for support is inherent in a complex OS (Score:1)
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
Re:I think the LDP has it backwards. (Score:1)
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
I think the LDP has it backwards. (Score:1)
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
obsolete unmaintained RAID HOWTO at linuxdoc (Score:1)
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
Re:obsolete unmaintained RAID HOWTO at linuxdoc (Score:1)
Whilst this would be good, its not likely to happen.
The old maintainer is a bit of a ghost, whilst i apluad him for his original effort, his current document is a great source of confusion to new raid users.
Glenn McGrath
Re:obsolete unmaintained RAID HOWTO at linuxdoc (Score:1)
"You dumb shit"
Pretty descriptive, do you have any techical details to backup your opinion?
I personally cannot understand why anyone with multiple drives wouldnt use a sotware raid.
Give me details of how wrong i am!
Re:ONE step in the right direction... (Score:1)
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.
Re:ONE step in the right direction... (Score:1)
<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!).
Re:obsolete unmaintained RAID HOWTO at linuxdoc (Score:1)
Well, Glenn, why not contact the LDP group with that exact question instead of posting it on /. (naw, don't take that as a flame - take that as encouragement to get involved.) Since you feel passionate about it - do something about it! Contact them, tell them what's wrong with the current one, and why you advocate it being replaced with the newer version. Provide them with a copy. That's what makes Linux and the whole Open Source community great - is it broken? If so, fix it, or at least tell someone so they can fix it!
Maintanance! (Score:1)
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!
Ouch! I've been DocForked! (Score:1)
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?
Well there are ways and ways.... (Score:1)
Hows about "The Linux Documentation in Public Libraries Project" ??
Re:Howto HOWTO! (Score:1)
What we need now... Good Hardware Database (Score:1)
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.
Sometimes, lack of docs are appropriate (Score:1)
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.
Re:Sometimes, lack of docs are appropriate (Score:1)
But lots of end user stuff has next to no instructions, it was this software i was having a go at.
sparkes
*** www.linuxuk.co.uk relaunches 1 Mar 2000 ***
One Markdown, four more to go.... (Score:1)
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."
Yeah well... (Score:1)
NEVER underestimate the ego of a egomaniac.
Abso-freakin-lutely! (Score:1)
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.
Re:Nice site, but why is the text so small? (Score:1)
Re:automated HOWTOs (Score:1)
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]
Getting there, but........ (Score:1)
Re:The new site is great. . . (Score:1)
Here's a dime kid, get yourself a real OS
maybe something similar to javadocs (Score:1)
Re:Open source docs (Score:2)
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.
The facelift is nice (Score:2)
Unfortunately, they are still no further in the transition from qwertz to DocBook [docbook.org] than they were three months ago.
There is not going to be a substantial change in the quality of the material until that happens.
Linuxdoc is not nearly expressive enough (Score:2)
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 [tuxedo.org] was tremendously important, and we've not seen a useful release of that yet, after a goodly two years.
Re:ONE step in the right direction... (Score:2)
> 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.
Re:ONE step in the right direction... (Score:2)
> 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.
Re:ONE step in the right direction... (Score:2)
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 Love You Guys (Score:2)
I'll send y'all valentines cards or something. But no chocolates this year; money's tight.
-Waldo
Re:I think the LDP has it backwards. (Score:2)
Sure. But what happens when you want to publish them on the web, or print them ? Your suggestion that you can just manually edit them ( try it some time !!! ) is not exactly practical. Then if a particular format is preferred it could be converted by the reader.
Simply put, It's not easy to convert all those HOWTOs, especially from a text format which has no logical structure. This goes from inconvenient to a user to simply disastrous for someone who wants to publish all the documents in a book or on a webpage. It also makes updating the documents in the alternate formats a time consuming and expensive process. If this was the way they did it, you would not be able to get the LDP docs in a book or on a website ( or the website would be hideously out of date and unmaintainable ).
Is it really worth putting the users through all that much grief just to save the authors the trouble of reading one page from the HOWTO-HOWTO ? Surely, good documentation first and formost is supposed to make life easy for the readers , and if a little effort on the author's part provides substantial benefits to the readers, isn't it worthwhile ?
Secondly, I'd like to take you up on your point about "learning Linuxdoc". ( You don't need to know anything about Docbook or XML. Linuxdoc is an SGML DTD like HTML ) Linuxdoc is extremely simple, and is a lot like html. It's summed up in one small section of the HOWTO-HOWTO. I learned it more or less instantaneously ( meaning I could go straight to work without wasting time "learning" ).
Re:Still SGML is required... (Score:2)
Sure. You don't do the conversion. sgmltools does it. The whole point of SGML is that it offloads the conversion to an SGML parser.
Why the f*ck does a documentation author have to be an expert in SGML processing, format conversion and other tricks?
One hardly needs to be an expert. You only need to read a page of the HOWTO-HOWTO. HOWTOs are not write-only, you know. I was up and running with Linuxdoc immediately. It is a ridiculously simple DTD. I don't believe someone who is too lazy to learn it will put in the effort to maintain a document, because the effort is somewhere between nothing and very little. As for complaining about "lack of document authors" ... where, and who ? I just submitted and they are swamped with incoming docs.
Instead of complaining,
You're the only one I see complaining.
why the f*ck don't they set up a conversion service, and accept contributions in a number of formats?
Because setting up the conversion service is very nontrivial. And because you simply can't pull logical structure out of an ASCII or Word or badly written HTML document. If you really do XML at work, you don't need to be told this.
Instead, they are proud in beeing able to generate the most useless formats out of their SGML markup graves.
PDF, Postscript, and HTML are hardly "the most useless formats".
But then please stop complaining about the lack of documentation writers!
I think you're misunderstanding my position. I am not complaining. I agree that they don't really have any right to complain either.
The fact that many good authors are just not able to handle the stuff means the loss of potential authors.
Authors that can read the HOWTO-HOWTO will not be lost.
Re:Still SGML is required... (Score:2)
Because plain text doesn't have any logical structure. It is almost impossible to convert. How do you know which text is a second level heading without some kind of directive that says so ? These kinds of directives are the kind of thing SGML takes care of. I hear of logical data rot, where daily GB's of data become unavailable due to loss of reader machines or software and a data format that is proprietory of a company gone bankrupt.
This is exactly the kind of problem SGML addresses. You stay away from proprietary formats. SGML is a W3 standard and is ASCII based. The advantage of SGML is that it allows you to put logical markup in your ASCII file. Basically, all you need to handle SGML is an SGML parser and something to map the tags in your DTD to formatting in your chosen document formats.
Re:I agree, but we need tools... (Score:2)
Not really true. ( as you'd know if you'd done any serious LaTeX use ). The biggest problem is that finding a picture format that is TeX-friendly and web-friendly is a nontrivial task. It's really the web's fault IMO -- most browsers only display bitmap-based graphics, as opposed to scalable graphics, which means that preparing device independent illustrations that can be viewed in a web browser is not terribly easy. This is a problem, but it's a much broader and bigger problem than you think.
Re:Linux Documentation Project needs: (Score:2)
In what format should the illustrations be kept in ? Bitmap formats like JPEG are a problem because they are not scalable ( they degrade when you resize ). Vector graphics formats are a problem because most web browsers don't support them. There is a problem, but solving it involves more than just drawing a few pictures.
Re:The ability to comment the Howtos on line (Score:2)
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 [thepuffingroup.com]
Re:One Markdown, four more to go.... (Score:2)
Then I assume, as a matter of principle, you have no GNU software on your computer, at all, right?
No GCC/EGCS, no GNU command-line utilities, no Gimp, no GNOME, no,...
well, you get the idea.
Re:The new site is great. . . (Score:2)
Obviously having a large amount of documentation in one place is excellent, and essential for wider take-up of Linux.
However, I don't find their site design user-friendly. The front page particularly is not aimed at people new to the site. We have nearly the whole page taken up with news and recent updates. The links you really want -- guides, FAQs, HOWTOs -- are stuck in the top-left hand corner.
Also, where are the security bulletins? I would have thought that was an essential part of a site like this. I can't even find them under "links". Did I just miss them?
Don't get me wrong, I shall be bookmarking this site and using it. But I don't think it's really ready for a general audience.
RH doesn't always include LDP (Score:2)
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.
FAQ-o-matic (Score:2)
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.
The ability to comment the Howtos on line (Score:2)
Re:automated HOWTOs (Score:2)
This sort of educational configuration management is what I miss in tools like linuxconf and cfengine.
production reasons (Score:2)
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.
Re:Biggest problems with linux documentation: (Score:2)
Too much work for me! I went back to Doom after a week or so...
Re:Still SGML is required... (Score:2)
I wrote my HOWTO (as my abstract says) because I had the same frustration writing docs. It's definately not easy to do, but tools like psgml, LyX, and (hopefully) WP 2000 will make it easier for anyone to write docs.
Re:Howto HOWTO! (Score:2)
-Mark
HOWTO HOWTO author
Too much help is not helpful (Score:2)
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.
Howto HOWTO! (Score:2)
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
DocBook is progress? (Score:2)
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 text so small? (Score:2)
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....
Nice Look (Score:2)
Well, I just looked at the LDP site [linuxdoc.org] 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 [faqs.org], but their search results are a real pain to wade through.
Just a thought.
Re:Still SGML is required... (Score:3)
Fine. Then please explain to us how you are going to automatically convert your documents to postscript, tex, ascii, rtf and PDF. Then explain how you would do the same if you had 1000 or so similar documents. Seriously, read the HOWTO-howto ( if you're too lazy to do that, you're probably too lazy to maintain a HOWTO ). SGML isn't that hard ( Linuxdoc is almost exactly the same as html ).
Here are some advantages of SGML:
- Emphasis on logical markup gives the HOWTOs a consistent "look and feel"
- Makes it easy to generate the documents in several formats -- postscript for printing, PDF or html for online reading, rtf for word processor compatibility.
- Makes long term storage more viable. For example, if you used HTML and some HTML tags became deprecated, your documents would be in an obsolete format. With Linuxdoc, you simply change your sgmltools converters to output the newer html / tex / whatever format.
In conclusion, I believe that if there's one thing the LDP got dead-right, it was the choice to use SGML.Biggest problems with linux documentation: (Score:3)
I know that ht/dig has been modified (for KDevelop via CoSource) to search local, rather than web based, files. I'd also love to see some really good, comprehensive, system-wide FAQs that tie into the rest of the help system ("How do I install a new network card?" links to the right part of the linux-networking HOWTO, etc).
--JRZ
automated HOWTOs (Score:3)
One reason Windows is popular is that Microsoft keeps finding new ways to make it easy to use the system. Ok, easy to crash too, but hey. If somebody were to take a particular HOWTO, and rework it into a script, it might turn out to be something vastly more useful for new Linux users who are used to Windows doing everything for you with its wizards and such.
This would be hard (Score:3)
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
Open source docs (Score:3)
The LDP does a great job of collecting all the relevent docs into one place but more often than not the how-to's wouldn't be needed if the guys on the project started to document there stuff better. how many times have you seen the install file say build it and use it or some such crap?
I recently installed a nameless piece of software that had a 10 line readme file! one line said if you don't know how to do this don't! what the f*** how the hell is this meant to encourage use?
We (the coders) need to start writing a little more, or at least finding a guy/gal who can write. Well I know what I am gonna have to do WRITE SOME DOCS lol.
sparkes
PS get in touch with you LUG to find willing doc writers! thats what I do
*** www.linuxuk.co.uk relaunches 1 Mar 2000 ***
ONE step in the right direction... (Score:5)
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.