So you want to help on the FAQ...

While help is always needed and appreciated, there are things that I ask you to do if you are submitting things to me for putting in the OpenBSD FAQ.

Be sure to read ALL of this page, and respect ALL the suggestions in it, not just the ones you think are relevant or make sense.


I have some priorities, they are (in no particular order):

NOT Priorities

Some things just are NOT priorities to me.

How do I help?

Changes to existing content

The "standard" way to pass around changes in the OpenBSD world is by way of "Unified Diff" against what is currently in the tree, created using a command similar to:
    cvs diff -u filename.html >filename.diff
Unified diffs are nice...after a short time, one can really start to "read" them directly.

As indicated above, though, if you send me a diff, make it good. One diff may cover multiple files, but it should only cover one type of change. In other words, a spelling correction should not also include new content. The diff should be against CURRENT source, not something a few months old. If I have to disassemble the diff... well, I probably won't. If new content, it should also be well-written and correct -- and let me know why you think it is correct, and have people (who I know and respect as authority) look it over.

Diffs aren't mandatory with me! If you see a problem, point it out and tell me what needs to change and what you think it should be. I'd rather have a general idea than a bad diff.

New Content

I write new content by creating a whole new file, writing in simple HTML that can be viewed by any browser, but missing all the header and footer stuff. When it is ready to be committed, I pull it into the page at the place I want it, add the Table of Contents entries, and commit it. Don't send me a diff for new content, send me this "just new content" file, unless you are ABSOLUTELY SURE you know where I'm going to put it and it is absolutely ready to commit. This way of writing makes it much easier to manage multiple new projects at one time until they are ready to be committed.

Be aware that "I think you should write a new article about ...." is NOT helpful. I can assure you that I have no problem coming up with ideas for new content, the hard part is making happen.

OpenBSD is a multi-platform OS. The FAQ has a clear i386-bias to it, however, don't submit a purely i386 article to me that isn't clearly marked in that way, or one that could easily be generalized to a more "multi-platform" style that isn't.

Don't hand me "rough" work: Trust me, I can throw together a bad article in about half an hour. The real time is in taking a rough idea and making it a good article. If you throw something together in half an hour, unless you write a LOT more rapidly than me, stop. Explore the topic more. Make it useful to more people. If there is really nothing more to add, ask yourself: "Does this article really matter?". Yes, adding man page links is a pain in the butt, but it is important, and no, I don't enjoy doing it anymore than you do.

When you write a new article and it is committed, help MAINTAIN it. Every six months, OpenBSD releases a new revision, which may alter the information in your article. We need to keep it up-to-date. You know the content of your article the best, AND you are very probably more knowledgeable in a topic than I am, as I never got around to writing it. So, your on-going support in maintaining what you write is important.

Don't talk, do

I get a lot of people telling me they will work on one thing or another. Very few of them come through. I don't want to spend hours telling you (and fifty other people) what I want, when very little ever shows up. If you prove to be someone who produces, I will spend time working with you, and even give you resources to work with. However, you will have to prove you actually SAVE me work, not make me work before I will be doing that. Sorry, but a lot of years on the team has proven to me that talk is very cheap and help is very rare.

"But, I don't want to spend a lot of time on something you will reject" I understand. I sympathize. If it is a really big project you are considering, sketch it out in a good outline, so I can quickly look at it and understand what you are considering, and ask me if I'm interested.

I will not "hold" a project for someone until they have shown me substantial work on it. If I have five people say to me "I'd like to write a softraid guide", I'll say "go for it" to all five, unless someone shows me some very good work in progress, as I know in all likelihood, out of the five people, none will actually come through.


FAQ Content Style

While I will be quick to say that the name "FAQ" is somewhat inaccurate at this point, I never want to hear the phrase "How to" associated with the FAQ or any other official OpenBSD documentation. People looking for a quick "How do I do this, don't tell me why, just tell me what to type" should be directed to Linux or Windows.

The FAQ should be a teaching document. "How do I" type questions should be followed by a detailed answer with lots of explanation, not just a "type this, don't ask why".

The FAQ is a secondary reference: if you can't find manual pages to link to that deal with your article, consider that there is probably a deficiency in the manual pages, and maybe that should be your first priority.

All new entries to the FAQ are going to be considered BSD licensed. You will be credited in the commit message, unfortunately we won't be able to do much more than that in most cases.

The "Dad" Test

I write for the FAQ as if I'm writing for my father: a very intelligent person who doesn't know anything about OpenBSD (in fact, I've used him to proofread and improve documentation before). Anticipate the questions the reader will ask, and answer them or link to answers. Pretend you don't know the topic you are writing about: does your article explain well? Does it point the user to where they should go for more information? Have someone intelligent who doesn't know OpenBSD read your article. When they ask you a "What do you mean by this?", take their comments seriously, ask yourself if it is really fair to expect that ALL OpenBSD users understand what you mean.

Don't use "TLAs". Spell it out. Or, as my father used to tell me, "Speak English, dammit!" (I think I have learned, he hasn't said this to me in many years!). An article cluttered with jargon and TLAs is difficult to read and usually says to the reader that the author is an arrogant bastard who is hiding their ignorance in big words or a lazy bum. If you really know a topic, you can explain it clearly and simply. There are some things that, spelled out, don't help: MODEM or RAM are good examples. However, referring to HD instead of spelling out "hard disk" is just uncalled for obfuscation. Many of our users are interested in many different fields, and your favorite TLA might mean something totally different to someone else. Was I the only person who spent a bit of time trying to figure out what Adobe Type Manager had to do with networking? (By the way, "TLA" stands for Three Letter Acronym. Did I make my point?)

"The FAQ is horribly disorganized!"

Yes, I know. And that is unlikely to change soon, and it is unlikely that fixing this is anything I will accomplish.

If you wish to show me a completely restructured and rewritten FAQ, please do so, but talking about it won't change anything.

"What should I work on?"

As with everything on the OpenBSD project, start with something that interests you and you think needs improvement.

If you are really interested in helping but not sure on what, here are some ideas I would like to have happen:

None of these are simple jobs. That's why they aren't done. If you are willing to give just a few hours to this project, please, don't even tell me, that's not what I'm talking about. Given time, I could accomplish all of those items. However, maybe you have skills in other areas than me, so don't let that list limit your imagination.

Holland Consulting home page
Contact Holland Consulting

since March 18, 2002 Published: 3/18/2002

$Id: faq-help.html,v 1.18 2010/02/26 03:58:04 nick Exp $