To the rest of list users; Please pardon another long email from me on this. Helping reasonable people like Robbert understand why many people consider "HOWTO's" to be harmful is hopefully worth the added noise and bandwidth.
On Sat, 26 Nov 2005 10:57:12 +0100, Robbert Haarman <[EMAIL PROTECTED]> wrote: >Dear JCR, > >Thank you for your informative message. > >> Things like "HowTo" documents, sites like openbsdsupport.org and lists >> like openbsd-newbie@ are more often than not considered garbage. The >> reason is simply because you are robbing the reader of the fundamental >> and important details that the reader _NEEDS_ to learn. By providing >> short-cut documents to just get things working, you are sabotaging the >> learning process of the reader. > >I see. That's a good point. > >> The "Quick Start" section of your document is missing a lot of things, >> in particular, the generally accepted way to "Quick Start" anything on >> OpenBSD. >> >> 1.) Read *_ALL_* relevant man pages, completely and repeatedly until you >> understand them. >> 2.) Search the mailing list archives for related information. >> 3.) Search the commit logs for any new developments and/or corrections. > >I will add these steps to the HOWTO, making it clear that nobody on the >mailing list should be bugged with questions before these steps have >been taken. > >> If end-users are lazy and want to take the easy way out, they should >> go back to using linux and MS-Windows. They are not welcome here. > >That's a pity. I personally think OpenBSD is the _only_ operating system >that takes security as seriously as it should be taken, and it would be >in everybody's (well, almost everybody's) best interest if they used it. >There is nothing wrong with the project not wanting certain users, but >it leaves these users with a choice among evils, which is a pity. > Both security and reliability are really nothing more than a byproduct of correctness and well informed decisions. There are many people on this planet who just want to _USE_ a computer for something, such as a task or entertainment, but they really have no desire to learn how things actually work, so they must rely on competent administrators to handle the details. The pity is not whether or not some users are welcome. The real pity is current technology has yet to produce a computer that the average user can, own, operate and maintain without either significant knowledge of their own or significant resources to pay professionals to do the dirty work. It is really no different than the history of the automotive industry. In the beginning when the complexity of technical advancements was not too prevalent, the knowledge needed for maintenance and repair was not a insurmountable impediment to car owners doing their own work. These days it's much different. >> People around here have been really trying to be polite recently. The >> thing that got me personally was realizing that these days there are >> young kids reading these lists. None the less, don't let my politeness >> fool you; I still think you are an arrogant, egotistical asshole who has >> shown blatant disregard for the education and well being of others as >> well as shown complete disrespect to the authors who spend their time >> and effort writing correct code and documentation so people can actually >> learn and do something useful. > >I really appreciate your politeness, and also appreciate you pointing >out your real feelings in no uncertain words. > >> If you really want me or anyone around here to change their mind about >> you and the crap you're producing, then replace your supposed "HowTo" >> with links to the relevant man pages. > >The reason I wrote the HOWTO is that, in my opinion of course, the >manpages don't make it clear how to set things up. Searching the >archives for more information came up with some contradictory messages, >and some instances of people being misled by the way things worked and >the way things were described in the manpages. My HOWTO is an effort to >gather the relevant information in one place, and provide clear steps >for getting things working. Therein lies a significant difference of opinion between you and I. The steps provided by HOWTO documents do not give clarity, instead they hand you a blindfold and tell you which way to walk. At times they might lead you to the correct destination but at other times they have you walk the plank. Regardless if you manage to reach your desired location, the blindfold has prevented you from observing your surroundings and learning from them. >Replacing the HOWTO with links to the >manpages is not an option, because, first of all, the manpages don't >provide the information that the HOWTO does, and secondly, the manpages >are already assumed to have been read, so linking to them again wouldn't >add anything. > >I completely understand your position that documentation should provide >the details people need to understand how things work. I agree with >that. I would have provided this information if I had, myself, known how >things work. However, I don't know this, and it seems the only way to >find it out would be to read the source code of various parts of the >kernel. Still, I figured I had learned enough to write a useful and >helpful document that at least described how to get things running. You >clearly think this is harmful; I think it might help some people. > Since you knew that you didn't really know, the result of your good intentions is nothing more than the blind leading the blind. To the rest of the world, your steps look a bit odd, kinda like the way Ray Charles and Stevie Wonder bob their heads while performing. >> If perchance this assessment of you and your work has incited you enough >> to turn on your personal flame thrower, > >Not at all. Your piece is very well reasoned and even you calling me an >arrogant asshole serves a good purpose. > A good purpose but still, I owe you an apology for that one. It was over the top and unnecessary. Unfortunately, you just happen to be the "Breaking Point" on this topic for many people around here including myself. >> It is my opinion that you have made a serious mistake by not >> knowing or not understanding the generally accepted consensus about >> correct documentation > >In that case, you couldn't have done better than to point it out to me, >and I'm very grateful that you did. > >> you won't change my mind or the minds of most long time users and >> contributors. > >I have no intention of doing so. I think your position is perfectly >valid. I also think my quest of providing clearer information and making >things more accessible is perfectly valid. I can only hope you agree. > >Sincerely, > >Bob > Dropping kicking an inexperienced user into the "Book of Man" is undoubtedly abrupt and in some ways unfair, so your quest of making things more accessible to a new user definitely has some validity. Since providing a blindfold and steps to follow is a fools game and fools gain, would you consider a different approach? There are times at conferences and in magazines where people put together articles about particular features in OpenBSD and they occasionally include a few configuration details. This approach is great but the goal is often to just highlight the feature, so people become aware that the feature exists rather than give complete details. Looking through history, once again, provides an alternative approach that might just work. In the days before the average person knew how to read, the person in the group who did know, preformed a "reading" from said Holy Book and along with a homily of explanation and insight for the passage. This age old tradition still exists in all cultures on the planet and in areas from religious to academic. You are legally able to copy the OpenBSD man pages, so there is really nothing stopping you from quoting them a chunk at a time and adding your own insight, explanations and experience. By privately contacting the authors and maintainers of both the code and man pages, you can easily double check your work to prevent spreading misinformation. Provide explanations of the steps you took as well as explanations of all the other possible steps a user might want or need to take. By the time you are done with such an endeavor and double check your work privately with others, you will at least know the subject matter well enough to provide useful instruction to others. It would be a lot of work and obviously, the result would be a lot longer than the man pages you include. None the less, a lengthy document providing a "reading" of the Techno-Latin from the "Book of Man" and a homily about what should be learned is far better than a HOWTO that claims to be a short-cut way to set up mirroring but actually provides the steps needed to possibly fry your disks through misconfiguration. There might be other good ways to go about making things more accessible to users but the methods you are currently using are really a disservice to others in spite of your good intentions. How would you feel if some newbie found your original HOWTO through google, never read your mailing list post asking for validation and followed your instructions only to lose all of his data due to your mistakes? Though I'm generally considered extremely good with information systems, I know damn well that mickey@ could geek-slap me into tomorrow without breaking a sweat. Trying to argue with him about your mistake only shows your inexperience and unwillingness to do things correctly such as actually researching the topic upon which you are trying to enlighten others. Your goal of making things more accessible is amiable and your intentions are good but your methods are seriously flawed. Writing a HOWTO without really knowing the subject matter or discussing it privately with those who do was nothing more than you taking the easy way out. If you wonder why other people seem offended by your good intentions, it is because you took the easy way out yourself as well as provided an easy way out for others. Doing things correctly takes a lot of time, effort and expertise. If you don't think correctness is important, then you will not find a lot of sympathy for your views around here, in fact, you'll find most people are extremely offended by them. If you really want to make the Techno-Latin in the man pages more accessible to mere mortals, you will need to do a lot more work than just lazily slapping the incorrect steps you invented on a HOWTO web page. If correctness was extremely important to you and you had extended the time and effort to ensure the greatest degree of correctness you could in your code and docs, would you be offended if I came along with an erroneous and lethargically tossed together "HOWTO" about your hard work? How about if I wanted to publicly argue with you that I'm right and you're wrong? In a nutshell, what you have done is perform sacrilege multiple times, on multiple fronts and against multiple people. Your insistence on keeping your "HOWTO" publicly available on the Internet indicates both your apologies and your claims of security being important are not sincere. Unless you are at least dedicated to, if not obsessed with, correctness your good intentions and amiable goals will continue to do more damage than good. You seem like a very reasonable person, so I hope you take step back from your personal perspective to think things through a bit more from other points of view. When you do, you'll see your Stevie Wonder impersonation is really quite impressive. ;-) Kind Regards, JCR
