On Fri, Nov 25, 2005 at 11:55:51AM -0500, Nick Holland wrote:
> We've been seeing a curious number of people offering various kinds of
> documentation on various OpenBSD topics.
>
> Most of them are somewhere between minimally useful and outright
> destructive and foolish. I think I've seen precisely one that is
> looking very promising...and that was sent to me privately, you haven't
> seen it yet. Obviously, bad documentation is in style now. However,
> people seem to be thrashing around on how to write bad documentation, so
> here are some tips based on experience with a number of recent
> submissions to [EMAIL PROTECTED]
>
>
> 1) Distribute your document in PDF file format.
> Yes, the Web is based on HTML, but hey, it is your document, make it
> PDF! There are at least a couple people who prefer that format (if all
> else fails, register a hotmail or yahoo e-mail address under another
> name, and say, "I prefer PDF!"). That way, people MUST add additional
> software to their system to read your document. People won't be able to
> send you diffs, so you can say honestly, "I received no useful change
> suggestions to this document, it MUST be good!". It also hides the fact
> that while you are claiming to be an OpenBSD expert, the only text
> editor/formatter you know how to use is MS Word. A PDF creation program
> will hide that very effectively.
>
> Bonus points for formats that are more obscure, less portable, or
> require over 500M RAM to open a two page document.
>
>
> 2) Write it as a HOWTO.
> Your reader just wants to know how to do the task they have at hand.
> After all, we know they are just wanting to accomplish the task, put it
> on their resume, and be elsewhere by the time it blows up. It won't be
> their problem by then, anyway! There is only one way to do most tasks,
> those extra knobs are there and set wrong just to confuse the new user,
> no one actually uses them differently, EVERYONE does things just like
> you suggest. Theo delights in adding extra "knobs" to OpenBSD and
> making sure they are set incorrectly. Rumors that he actively removes
> nonsense options are completely untrue.
>
> No one cares about life-cycle-related issues like upgrades or recovering
> from system failures or disasters.
>
> Besides, it is funny to watch people for whom English is not their first
> language think "howto" is a valid English word, and is often used with a
> question mark at the end ("Howto get my mouse working?"), as a
> replacement for "how do I ...?".
>
>
> 3) Write it for an older release.
> 3.8 was only just shipped, there are surely more 3.7 or 3.6 users that
> could benefit from your writing then there are 3.8 users, right? The
> fact that improvements in the most recent release make much of your work
> incorrect or less than ideal isn't your problem...
>
>
> 4) Publish it, let it rot.
> Don't waste time bringing/keeping your old documents up to date. There
> are so many other things you could be doing, instead. People will
> figure it out. After all, books don't automatically update on your
> shelf, why should a web page be any different? Besides, PDF files are a
> pain to edit, and this way, you don't have to keep track of where you
> left the original source.
>
>
> 5) Write a rough draft, put it on misc@, and let the community decide if
> it is useful or accurate.
> That's what the Internet is about, right? Freedom to say any damn thing
> you wish, regardless of accuracy. You are supporting free speech,
> that's a good thing, right? BTW, all the people who say you are going
> about things wrong are just plain dumb, don't let their @openbsd.org
> e-mail addresses fool you. E-mail can be easily spoofed. Or they are
> trying to repress you.
>
> BTW: The more people you can get irate about your article and tell you
> so publicly on the mail lists (quoting the link to your article), the
> higher it will be in Google's rankings, permitting more people to find
> your wisdom!
>
>
> 6) Good formatting and pretty graphics mean more than actual content.
> Obviously, if your page LOOKS good, it must be good. Complex things
> like CSS and browser-specific tricks are great! Compared to the lame
> OpenBSD website, you will look like an absolute authority!
>
>
> 7) When you don't know what is going on, just tell everyone to do what
> got things to (sorta) work for you. Don't waste time by researching
> your topic completely, or privately asking people in-the-know to verify
> key facts.
> The difficulty is clearly the result of the sloppy work of the OpenBSD
> developers. Acknowledging your ignorance of a topic clears your
> conscience. Just say, "I don't understand this, but it worked for me,
> so everyone should do this".
>
>
> 8) If you got the thing to work, you are qualified to write a HOWTO.
> The more you investigate something, the more annoying issues and special
> cases (like maintainability) come up, so don't waste your time.
>
>
> 9) An hour or two is sufficient to spend writing a HOWTO.
> Anything more than that is just wasting your time. The reader will
> figure out the things you glossed over. They were doing that before you
> came along, you are helping them, so this is a net improvement, right?
>
>
> 10) Demand that it be put on the OpenBSD website.
> Hey, if they don't like it, that can make the tiny little changes
> needed. After all, didn't Thomas Edison say "Genius is one percent
> perspiration and ninety-nine percent inspiration"? You provided the
> inspiration, they can do the one percent perspiration, right? Since
> they are an open source project, and they do work for free, you have
> every right to demand they adopt your recommendations, after all, they
> have no clear direction without you.
>
>
> Ah, you will note that I failed my own list here, as I called this a
> HOWTO, but provided way too much explanation about why you should follow
> these tips. Hey, writing sucky documentation is a difficult skill!
>
>
> (hopefully, the tongue-in-cheek (or head-in-toilet) nature of the above
> was obvious.)
>
> Nick.
That's just true. Nothing else.
Am i allowed to publish this on on a website of mine?
Jonathan
--
| /"\ ASCII Ribbon | Jonathan Glaschke - Lorenz-Goertz-Stra_e 71,
| \ / Campaign Against | 41238 Moenchengladbach, Germany;
| X HTML In Mail | jabber: [EMAIL PROTECTED]
| / \ And News | http://jonathan-glaschke.de/
