If every nook and cranny isn't documented, how exactly is it you expect professional authors to learn them?
"Perhaps professional authors would like to join the open source movement and start authoring for OSS projects for no pay. I just wouldn't hold your breath waiting for that"
Professional programmers work on open source projects, some with and some without pay. What on earth makes you assume these things have to be done without pay?
In many cases there is a commercial conflict of interests on open source projects though. Usually the prominent developers get paid for support (either directly or by co-authoring books), there wouldn't be as much demand for this with good solid documentation.
Read what you just quoted there again and think about it. Also RPMS are a packaging format, not an end user installer. Almost no project distributes RPMS or any other binary format, with or without an installer.
"I've never had a problem with Apache's documentation. The only time I've looked for a tutorial-style document and been dissatisfied was when I was trying to set up SSL (this is back when many distros,"
SSL would be a fine example then, it's a trivial requirement of pretty much everybody who is setting up a webserver, even if they aren't going to buy a cert pretty much everybody needs ssl for something.
"Remember that, until the Web got big, anonymous ftp was simply how you distributed *everything*."
Although that was how you distributed everything before the web got big, that concept is over 10yrs out of date. Certainly anonymous ftp should be covered in the docs, but other configurations should be as well.
"True enough, but this isn't really a documentation issue -- it's just a legacy of how *IX systems are generally used."
Nah it's a documentation issue, unless of course the app doesn't support functioning this way, then it's a legacy issue. If the app does support a mode of operation more suited to non-isp/web hosting configurations, it should be documented.
"
Stories
Old Stories
Old Polls
Topics
Hall of Fame
Submit Story
About
Supporters
Code
Awards
Services
Broadband
Online Books
PriceGrabber
Product News
Tech Jobs
IT Research
Re:Brian Jones Re:Brian Jones (Score:1) by 0x0d0a (568518) on Thursday July 29, @02:02PM (#9835086) mysql (almost all the documentation is wrong, and I mean the simplest stuff is wrong, like working with authentication). They have lots of documentation, but most of it is inaccurate, out of date, and in many cases was ALWAYS wrong. They rely too much on the ability of users to comment on given pages of documentation. But those users are wrong half the time, and even when they are right their contributions don't seem to ever be added.
I confess that I've never seriously used mysql. I was impressed with the presentation of their docs, but they certainly could be wrong, and I wouldn't know.
Apache, dear god just look at it. Their documentation is basically a quick reference, they list all kinds of options and generally out of context. Have these people never heard of tutorials?
I've never had a problem with Apache's documentation. The only time I've looked for a tutorial-style document and been dissatisfied was when I was trying to set up SSL (this is back when many distros,
I've yet to find a ftp server with good docs either, again the same problem. In the case of ftp servers they seem to have an obsession with large anonymous ftp (aside from universities and large software vendors who actually wants to do this?).including Red Hat, didn't ship SSL support, so very few people could it).
I use vsftpd -- I admit that it isn't a very complicated ftpd, but it's certainly not hard to find what you're looking for.
Remember that, until the Web got big, anonymous ftp was simply how you distributed *everything*.
If any other option they give the ability to have users log into their system accounts home directory, talk about a pain in the arse to manage and keep seperate from other services. I suppose if you were doing web hosting this is what you'd want, but not for anything else.
True enough, but this isn't really a documentation issue -- it's just a legacy of how *IX systems are generally used.
Most things assume that actually using the software is obvious, or the other way, they assume you've had no problem installing.
I dunno. When was the last time that you had a set of good documents on what to do if your closed-source Windows applications failed to install?
I'd say that in general (even aside from documentatin), software doesn't deal too well with failure to install. You generally have to have a pretty good idea of what you're doing to fix a failure to install."
99% of the time windows applications don't fail to install in the form they are
The programmers themselves should NOT be providing the documentation, they should be recruiting volunteers for that purpose.
The documentation is for both experienced and inexperienced users, and assuming experienced users know ANYTHING about the program itself before reading the documentation is absurd.
Full documentation, and no I'd completely disagree, it should NOT be a book sold by a 3rd party.
We need better docs than that. It does need to be dumbed down for 3yr olds. There should be a hand hold through installation, configuration examples, references (which include examples for everything they reference. And at the very least links to the same provided by the third party when knowledge of something 3rd party is required.
Why? Not everyone is an idiot, but most people aren't "fairly smart, experienced". Most people are fscking stupid and admins are no exception, users are the very definition. But even if they were all fairly smart, nobody knows everything and I daresay that most have holes in their knowledge.
You need to provide enough information to fill the gaps. A reference for those who don't need the holes filled is essential too (though it should have examples illustrating each of the options).
Hell the biggest problem I have is "values" no matter what it is, all documentation seems to assume you know what unit they want the value specified in. If they were all bytes or kbytes or what have you, that would be fine. But SOME are bytes, SOME are kbytes, some are even mbytes, etc. Across the board with open source apps, they never seem to want to tell you that simple but very critical piece of information.
While I'm sure there are a couple small projects with crap documentation. There are no shortage of LARGE projects with crap documentation.
mysql (almost all the documentation is wrong, and I mean the simplest stuff is wrong, like working with authentication). They have lots of documentation, but most of it is inaccurate, out of date, and in many cases was ALWAYS wrong. They rely too much on the ability of users to comment on given pages of documentation. But those users are wrong half the time, and even when they are right their contributions don't seem to ever be added.
Apache, dear god just look at it. Their documentation is basically a quick reference, they list all kinds of options and generally out of context. Have these people never heard of tutorials?
Bind... bind is scarey as hell, you find conflicting and inaccurate information EVERYWHERE not just on the website. For instance, look for information on how to setup reverse lookups. You won't find any actual tutorial type information at all, explaining simply how reverse lookups work and giving a couple examples. Nope, what you'll find are lots of people posting new information about old versions of bind. They give incorrect syntax that simply doesn't work almost every time.
Thinking about it, I can't honestly say I've EVER found a bind example on the web that worked without modification. From ANY source.
I've yet to find a ftp server with good docs either, again the same problem. In the case of ftp servers they seem to have an obsession with large anonymous ftp (aside from universities and large software vendors who actually wants to do this?).
If any other option they give the ability to have users log into their system accounts home directory, talk about a pain in the arse to manage and keep seperate from other services. I suppose if you were doing web hosting this is what you'd want, but not for anything else.
Most things assume that actually using the software is obvious, or the other way, they assume you've had no problem installing.
Very few give configuration examples. Some sites give a couple limited examples but don't give examples of usage for the config options. Some give the config options but no configuration examples, like apache. Some do either of those or both but don't cover how to install the software.
COMPLETE Documentation is needed, that covers everyone from complete novice and idiot who nothing nothing about the app or the OS to power users who know nothing about the app. Even advanced documentation should be written from the perspective that the user knows nothing about the app.
Because after all an advanced user, who knows alot about webservers and nothing about apache, is going to be looking at adanced topics the first day they are playing with apache.
The docs should take you from novice to guru, include tutorials, include a hand hold through installation.
References are good but they don't replace the need for any of the rest of it.
The docs should also always apply to the latest stable version, if the docs havent been checked and updated, then the new version isn't stable yet. The docs should be considered part of the release.
Reality is that most sysadmins DO need the same level of documentation.
And further most sysadmins are NOT programmers. comments in source/headers is a completely inappropriate answer. We could hope that most sysadmins might know what source code is, but headers is pushing it.
Remember 99% of these guys read a certification book, passed a test, and now have a job.
I think your missing the point. We are talking about sysadmin and end user documentation here. It is safe to assume they don't know what source code is, let alone to look for comments there.
Documenting the source is great and all, but it's more important to document HOW THE HELL TO USE THE PROGRAM.
All the links point to the page your on. If the layout, grammar, and wording appear correct on the mail then the next test is the links and there are a number of ways to verify the link/page your on.
If answering in complete honesty I'd have to say ever single one of these is fraudulent because the links point back to the survey site... all of them.
Some grey areas most definately should be left grey. For instance there may well be people who can have a dvd playing and still focus on the road, perhaps they listen while the passengers watch.
As for guns, it's not a matter of opinion and hasn't been for a long time. Countries/states/areas with strict gun control have the highest crime rates, while those with gun REQUIREMENTS or no control have the lowest.
Of course switzerland being the best example. All citizens are required to have arms and despite the amazing wealth floating around switzerland, it has the lowest crime rate in the world. Those are facts, not opinions.
Further the right to bear arms is constitutional, it's the highest law of the land and no body of government is SUPPOSED to have the authority impead on it in any fashion... including limiting or imposing restrictions upon it.
"lots more people think"
That's ridiculous, lots more DO NOT think it dangerous. Even if they did however, the majority does NOT rule nor should it (also a historical fact). Our government is NOT based on the concept of majority rules nor has it ever been. Even the election process of our President was devised in such a manner as to prevent (as per "The Patriots Handbook") a direct ruling of the unwashed masses.
Why? Because quite frankly, the MAJORITY of people, are idiots who believe whatever ideals their spoonfed. If left to their own they will choose based on ideal rather than harsh reality, and those who won't will usually accept harsh reality to be whatever they are told it is.
Quite frankly, I think even the crazed conspiracy theorists would be more fit to rule than the "majority". At least their more realistic and properly paranoid.
Having handled classified material I can tell you, while the conspiracy theorists are usually wrong, they are much closer to the truth than the majority.
The amiga is defunct, DR-DOS was just an MS-DOS clone.
Check out your windows a/v software and see what it protects against, there are over 200,000 viruses floating around for windows.
Even among the historical systems your talking about less than 50 total for other operating systems. In my mind at least that's a fairly significant gap.
I was emphasized too much. It's actually probably closer to 99.995%.
Although they only hold 93% of the market last I checked (96% according to some sources), 99.999999999999999% of viruses only affect windows, and/or Microsoft applications. Between fingers and toes (haven't tried honestly) you might just manage to count all the viruses which have affected OTHER platforms combined throughout history... and you don't need any digits to count the number that affect other platforms NOW.
So obvious answer, rape, pillage and murder anywhere you see a windows box. You will see a dramatic decline in viruses. Harmful viruses will generally decrease proportionately to the murdering of course... the raping and pillaging are purely recreational and perfectly harmless if accompanied by murdering anyway.
Besides, I'm almost positive it's in the commandments somewhere... Thou shalt act with holy vengence and slain my enemies who come flying the butterfly standard.
Someone talking about how "many years ago" he mistook a socket A for a 370. Sheesh.
I remember not so many years ago when intel and AMD processors really did use the same socket... I wish history would start repeating itself real soon, I'm sick of different sockets.
When will we see the return of common sockets on the desktop and server for both intel and amd processors? I'm starting to get annoyed with having to pay attention.
This doesn't mean a 300mbit internet connection anymore than 802.11g means 100mbit. Hell most wireless internet connections are NOWHERE NEAR as fast as the 11mbit pipe their running on now.
I dunno, that peak in the center could just be the carefully hidden tip of the laser.
That picture looks like it was still taken from aways off and surely the Empire wouldn't want a passing shuttle to uncover it.
Nope, short of a closer look, possibly a few rovers and manned flights I think for now we better continue to assume that it IS in fact a space station planning the immenient distruction of earth. Likely they were on their way here and ran out of gas.
Slashdot Mirror
If every nook and cranny isn't documented, how exactly is it you expect professional authors to learn them?
"Perhaps professional authors would like to join the open source movement and start authoring for OSS projects for no pay. I just wouldn't hold your breath waiting for that"
Professional programmers work on open source projects, some with and some without pay. What on earth makes you assume these things have to be done without pay?
In many cases there is a commercial conflict of interests on open source projects though. Usually the prominent developers get paid for support (either directly or by co-authoring books), there wouldn't be as much demand for this with good solid documentation.
"RPMs?"
Read what you just quoted there again and think about it. Also RPMS are a packaging format, not an end user installer. Almost no project distributes RPMS or any other binary format, with or without an installer.
"I've never had a problem with Apache's documentation. The only time I've looked for a tutorial-style document and been dissatisfied was when I was trying to set up SSL (this is back when many distros,"
SSL would be a fine example then, it's a trivial requirement of pretty much everybody who is setting up a webserver, even if they aren't going to buy a cert pretty much everybody needs ssl for something.
"Remember that, until the Web got big, anonymous ftp was simply how you distributed *everything*."
Although that was how you distributed everything before the web got big, that concept is over 10yrs out of date. Certainly anonymous ftp should be covered in the docs, but other configurations should be as well.
"True enough, but this isn't really a documentation issue -- it's just a legacy of how *IX systems are generally used."
Nah it's a documentation issue, unless of course the app doesn't support functioning this way, then it's a legacy issue. If the app does support a mode of operation more suited to non-isp/web hosting configurations, it should be documented.
"
Stories
Old Stories
Old Polls
Topics
Hall of Fame
Submit Story
About
Supporters
Code
Awards
Services
Broadband
Online Books
PriceGrabber
Product News
Tech Jobs
IT Research
Re:Brian Jones
Re:Brian Jones (Score:1)
by 0x0d0a (568518) on Thursday July 29, @02:02PM (#9835086)
mysql (almost all the documentation is wrong, and I mean the simplest stuff is wrong, like working with authentication). They have lots of documentation, but most of it is inaccurate, out of date, and in many cases was ALWAYS wrong. They rely too much on the ability of users to comment on given pages of documentation. But those users are wrong half the time, and even when they are right their contributions don't seem to ever be added.
I confess that I've never seriously used mysql. I was impressed with the presentation of their docs, but they certainly could be wrong, and I wouldn't know.
Apache, dear god just look at it. Their documentation is basically a quick reference, they list all kinds of options and generally out of context. Have these people never heard of tutorials?
I've never had a problem with Apache's documentation. The only time I've looked for a tutorial-style document and been dissatisfied was when I was trying to set up SSL (this is back when many distros,
I've yet to find a ftp server with good docs either, again the same problem. In the case of ftp servers they seem to have an obsession with large anonymous ftp (aside from universities and large software vendors who actually wants to do this?).including Red Hat, didn't ship SSL support, so very few people could it).
I use vsftpd -- I admit that it isn't a very complicated ftpd, but it's certainly not hard to find what you're looking for.
Remember that, until the Web got big, anonymous ftp was simply how you distributed *everything*.
If any other option they give the ability to have users log into their system accounts home directory, talk about a pain in the arse to manage and keep seperate from other services. I suppose if you were doing web hosting this is what you'd want, but not for anything else.
True enough, but this isn't really a documentation issue -- it's just a legacy of how *IX systems are generally used.
Most things assume that actually using the software is obvious, or the other way, they assume you've had no problem installing.
I dunno. When was the last time that you had a set of good documents on what to do if your closed-source Windows applications failed to install?
I'd say that in general (even aside from documentatin), software doesn't deal too well with failure to install. You generally have to have a pretty good idea of what you're doing to fix a failure to install."
99% of the time windows applications don't fail to install in the form they are
The programmers themselves should NOT be providing the documentation, they should be recruiting volunteers for that purpose.
The documentation is for both experienced and inexperienced users, and assuming experienced users know ANYTHING about the program itself before reading the documentation is absurd.
Full documentation, and no I'd completely disagree, it should NOT be a book sold by a 3rd party.
Personally I'm not crazy about Python. And then you add this .net thing into the picture, I'm especially not crazy about that.
.net written by a Microsoft employee?
But then, to top everything else off, you add a version of python for
Forgets cops, I want a new show called Scammers, Spammers, and Nigerian pimps!
We need better docs than that. It does need to be dumbed down for 3yr olds. There should be a hand hold through installation, configuration examples, references (which include examples for everything they reference. And at the very least links to the same provided by the third party when knowledge of something 3rd party is required.
Why? Not everyone is an idiot, but most people aren't "fairly smart, experienced". Most people are fscking stupid and admins are no exception, users are the very definition. But even if they were all fairly smart, nobody knows everything and I daresay that most have holes in their knowledge.
You need to provide enough information to fill the gaps. A reference for those who don't need the holes filled is essential too (though it should have examples illustrating each of the options).
Hell the biggest problem I have is "values" no matter what it is, all documentation seems to assume you know what unit they want the value specified in. If they were all bytes or kbytes or what have you, that would be fine. But SOME are bytes, SOME are kbytes, some are even mbytes, etc. Across the board with open source apps, they never seem to want to tell you that simple but very critical piece of information.
While I'm sure there are a couple small projects with crap documentation. There are no shortage of LARGE projects with crap documentation.
mysql (almost all the documentation is wrong, and I mean the simplest stuff is wrong, like working with authentication). They have lots of documentation, but most of it is inaccurate, out of date, and in many cases was ALWAYS wrong. They rely too much on the ability of users to comment on given pages of documentation. But those users are wrong half the time, and even when they are right their contributions don't seem to ever be added.
Apache, dear god just look at it. Their documentation is basically a quick reference, they list all kinds of options and generally out of context. Have these people never heard of tutorials?
Bind... bind is scarey as hell, you find conflicting and inaccurate information EVERYWHERE not just on the website. For instance, look for information on how to setup reverse lookups. You won't find any actual tutorial type information at all, explaining simply how reverse lookups work and giving a couple examples. Nope, what you'll find are lots of people posting new information about old versions of bind. They give incorrect syntax that simply doesn't work almost every time.
Thinking about it, I can't honestly say I've EVER found a bind example on the web that worked without modification. From ANY source.
I've yet to find a ftp server with good docs either, again the same problem. In the case of ftp servers they seem to have an obsession with large anonymous ftp (aside from universities and large software vendors who actually wants to do this?).
If any other option they give the ability to have users log into their system accounts home directory, talk about a pain in the arse to manage and keep seperate from other services. I suppose if you were doing web hosting this is what you'd want, but not for anything else.
Most things assume that actually using the software is obvious, or the other way, they assume you've had no problem installing.
Very few give configuration examples. Some sites give a couple limited examples but don't give examples of usage for the config options. Some give the config options but no configuration examples, like apache. Some do either of those or both but don't cover how to install the software.
COMPLETE Documentation is needed, that covers everyone from complete novice and idiot who nothing nothing about the app or the OS to power users who know nothing about the app. Even advanced documentation should be written from the perspective that the user knows nothing about the app.
Because after all an advanced user, who knows alot about webservers and nothing about apache, is going to be looking at adanced topics the first day they are playing with apache.
The docs should take you from novice to guru, include tutorials, include a hand hold through installation.
References are good but they don't replace the need for any of the rest of it.
The docs should also always apply to the latest stable version, if the docs havent been checked and updated, then the new version isn't stable yet. The docs should be considered part of the release.
Reality is that most sysadmins DO need the same level of documentation.
And further most sysadmins are NOT programmers. comments in source/headers is a completely inappropriate answer. We could hope that most sysadmins might know what source code is, but headers is pushing it.
Remember 99% of these guys read a certification book, passed a test, and now have a job.
I think your missing the point. We are talking about sysadmin and end user documentation here. It is safe to assume they don't know what source code is, let alone to look for comments there.
Documenting the source is great and all, but it's more important to document HOW THE HELL TO USE THE PROGRAM.
All the links point to the page your on. If the layout, grammar, and wording appear correct on the mail then the next test is the links and there are a number of ways to verify the link/page your on.
If answering in complete honesty I'd have to say ever single one of these is fraudulent because the links point back to the survey site... all of them.
I thought that went without saying, this is after all supposed to be a planetbuster right? :P
Some grey areas most definately should be left grey. For instance there may well be people who can have a dvd playing and still focus on the road, perhaps they listen while the passengers watch.
As for guns, it's not a matter of opinion and hasn't been for a long time. Countries/states/areas with strict gun control have the highest crime rates, while those with gun REQUIREMENTS or no control have the lowest.
Of course switzerland being the best example. All citizens are required to have arms and despite the amazing wealth floating around switzerland, it has the lowest crime rate in the world. Those are facts, not opinions.
Further the right to bear arms is constitutional, it's the highest law of the land and no body of government is SUPPOSED to have the authority impead on it in any fashion... including limiting or imposing restrictions upon it.
"lots more people think"
That's ridiculous, lots more DO NOT think it dangerous. Even if they did however, the majority does NOT rule nor should it (also a historical fact). Our government is NOT based on the concept of majority rules nor has it ever been. Even the election process of our President was devised in such a manner as to prevent (as per "The Patriots Handbook") a direct ruling of the unwashed masses.
Why? Because quite frankly, the MAJORITY of people, are idiots who believe whatever ideals their spoonfed. If left to their own they will choose based on ideal rather than harsh reality, and those who won't will usually accept harsh reality to be whatever they are told it is.
Quite frankly, I think even the crazed conspiracy theorists would be more fit to rule than the "majority". At least their more realistic and properly paranoid.
Having handled classified material I can tell you, while the conspiracy theorists are usually wrong, they are much closer to the truth than the majority.
The amiga is defunct, DR-DOS was just an MS-DOS clone.
Check out your windows a/v software and see what it protects against, there are over 200,000 viruses floating around for windows.
Even among the historical systems your talking about less than 50 total for other operating systems. In my mind at least that's a fairly significant gap.
I was emphasized too much. It's actually probably closer to 99.995%.
Remember when the SGI 512 processor story came out and all those "imagine a beowulf cluster of these" jokes were modded down?
Now we have to go back and mod them insightful
Although they only hold 93% of the market last I checked (96% according to some sources), 99.999999999999999% of viruses only affect windows, and/or Microsoft applications. Between fingers and toes (haven't tried honestly) you might just manage to count all the viruses which have affected OTHER platforms combined throughout history... and you don't need any digits to count the number that affect other platforms NOW.
So obvious answer, rape, pillage and murder anywhere you see a windows box. You will see a dramatic decline in viruses. Harmful viruses will generally decrease proportionately to the murdering of course... the raping and pillaging are purely recreational and perfectly harmless if accompanied by murdering anyway.
Besides, I'm almost positive it's in the commandments somewhere... Thou shalt act with holy vengence and slain my enemies who come flying the butterfly standard.
NG, that's hardly the point now is it?
"That way we get your P4's for cheap"
;)
Why? you can get a superior athlon chip now
Someone talking about how "many years ago" he mistook a socket A for a 370. Sheesh.
I remember not so many years ago when intel and AMD processors really did use the same socket... I wish history would start repeating itself real soon, I'm sick of different sockets.
When will we see the return of common sockets on the desktop and server for both intel and amd processors? I'm starting to get annoyed with having to pay attention.
I for one welcome our new dark energy overlords!
In what way does this differ from a linux VM, what are the up's and downs?
This doesn't mean a 300mbit internet connection anymore than 802.11g means 100mbit. Hell most wireless internet connections are NOWHERE NEAR as fast as the 11mbit pipe their running on now.
That's backward, it's usually the business version that has a jacked up price.
If something claims to be for industrial or business use, normally it costs at LEAST twice what the consumer version does.
I dunno, that peak in the center could just be the carefully hidden tip of the laser.
That picture looks like it was still taken from aways off and surely the Empire wouldn't want a passing shuttle to uncover it.
Nope, short of a closer look, possibly a few rovers and manned flights I think for now we better continue to assume that it IS in fact a space station planning the immenient distruction of earth. Likely they were on their way here and ran out of gas.