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.
- Make it relevant. Give me additions that really make the FAQ
better in some way. There are several groups of people to consider when
making changes: readers, maintainers, and translators. If your change
doesn't improve life for at least one of those groups, ask yourself
Changing ">" characters to ">" makes more work for
maintainers (harder to read), more work for translators, and doesn't
change the presentation to the reader ONE BIT.
- Give me complete work. If you are sending me a spelling correction
diff, send me a complete spelling correction diff - so that when it is
committed, I can say "This document is spell checked and correct" (or
at least, the same error doesn't exist in five other places on the same
If you add man page links to an article, check the CONTENT of the
article, and only link to man pages that are relevant, not just
containing the same sequence of characters. Adding links to a factually
incorrect article is bad.
- If you send me diffs, make 'em good. If you send me a
single diff with
thirty changes in it, and ten of them are things I don't agree with,
I have a mess separating the stuff I agree with from the stuff I don't.
For this reason, only send one type of change per diff. OR, tell me
what you don't like and how you think it should be changed -- I find
this is often far easier than making sense of a bad diff.
- Write using a text editor, not an HTML editor. HTML editors do
unpleasant things sometimes, things that can really make the CVS
process a mess.
I use standard OpenBSD vi(1), with a few macros in a .exrc file.
- Spell checkers are great. Grammar checkers suck. Please don't
run a FAQ page through Word's grammar checker and take its output as
gospel, or even directly useful.
I VERY often disagree with the
suggestions of automated grammar checkers. General guideline: If you
need an automatic grammar checker to spot an error...it isn't an
error. Remember, the goal is to make the FAQ more USEFUL to people,
this isn't fine literature. Besides, fine literature rarely passes a
I have some priorities, they are (in no particular order):
- Errors: Factual inaccuracies in the FAQ. (ok, these are top priority)
- Preparation for the next release of OpenBSD
- Gross unclearness or incompleteness
- New, relevant content
Some things just are NOT priorities to me.
occurs in the
A link should be USEFUL and relevant to the reader, not just a "Oh, look, I
made a contribution to the FAQ". Too many links are just a distraction.
Generally, unless a link really adds to the document, respect the author's
work. In some places in the FAQ, there is a blatant shortage of links, and
adding would help -- go ahead, add. In other places, if someone misses
the eight reference to the same blooming man page, WHO CARES???
- HTML Cleanup: At this time, the HTML used in the FAQ should pass
validation test. We'd like to keep it that way.
HOWEVER, there are a lot of different validation programs out there, we
picked ONE. Validation does serve a purpose for the maintainers: it
helps us spot blatant HTML errors. By itself, it does nothing for users.
Validated code is not sufficient for usable HTML, nor is it required.
Don't waste my time with nonsense changes your favorite validator wants
us to make if it doesn't improve life for someone.
- Do NOT submit trivial "judgment call" changes. Believe it or not,
there are multiple acceptable ways to do some things. If you make a
trivial change that does not clearly improve the document, tomorrow
someone else may decide they like it better the other way and change it
again. You do this, and you may well find yourself with a lot of
translators very, very angry with you. Don't piss off the translation
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
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.
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
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 HTML Style
- Simple HTML, should be very clearly readable on any likely browser.
My list of "test browsers" for anything that is a basic formatting change
includes Firefox, Chrome, Dillo, Netscape 4, lynx, w3m, Internet Explorer.
However, in general, don't be looking at basic formatting changes, or
introducing new formatting tricks. What is there already works well.
- faq3.html or
faq4.html are good
examples of style. Yes, you will see some inconsistencies. Sorry.
- Use short tags wherever possible.
etc. Yes, I know, some HTML guides suggest just the opposite. Tough.
- <b> is preferred to <strong>
- <i> is preferred to <em>
- Do NOT use closing tags that are not required for HTML compliance,
such as </p> or </li>.
They just irritate us.
- If you are modifying an existing article, respect the original author's
style as much as possible, even if it is in conflict with something else here.
Don't bother re-styling an existing article at this time, until a more formal
"style" document is created.
- man page links should look something like this:
Note that in some cases, you should add platform specific or OpenBSD
release specific info in there, using the arch= and/or
manpath= options, though they should NOT be used unless there
is reason. Do not include options that aren't needed, nor do you want
to leave out anything that IS needed.
- Lines should wrap around 72 chars when possible, unfortunately, man
page links are never going to work with that.
- Splitting tags: If you wish to split a long line, for example, a man
page link, there are right ways and wrong ways to do it:
The reason for this is a "newline" will be rendered as a space in the
browser, some browsers will display the first as
" entry(number)" (note the leading space being marked as
part of a link). Use of these "split" lines is optional.
- New sentence, new line. This is a guideline for new additions to
the FAQ, in order to help reduce the size of diffs caused by one-word
changes. At this time, we are not interested in changing old articles
to this style, however new changes should have the change "ended" by
a line break where appropriate. So yes, you will see old articles
with occasional strange short lines.
- Whitespace: use sparingly. Blank lines are good. VERY SMALL (i.e.,
one to four spaces) indentation where it helps readability is good.
"Pretty formatting" which tries to make HTML look like a structured
programming language is a joke, just makes it look cute, but makes
maintenance difficult and makes
the page take longer to load. Do not use tab characters, either in
printing or non-printing places (different browsers may render tabs
differently, and they can create some odd whitespace only diffs).
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
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.
- faq11.html is now the X FAQ. Multi-platform X information --
configuration, multi-headed, links to sample X config files.
(I've got a good start on this, but there is a LOT of content that
could be added yet. Hint: cwm).
- A "Frequently Asked Questions about Ports" page. (possibly tied to
the existing ports stuff, possibly not).
This would questions about individual ports, not about the ports
- Update the faq9
Linux/OpenBSD co-existence info.
This is rather difficult, as there are so many Linux variations out
I'd like to further improve this section for people coming to OpenBSD
from other Unix-like OSs.
- Some info on the new IPSec stuff.
- Something on contributing code to the project
- faq14.3 needs a complete rework. Nothing is sacred here, even
the topic is fair game.
- softraid (well underway by me)
- Watch misc@, and see what commonly asked questions pop up there.
Or even really good questions that don't pop up frequently.
- rdist is cool.
Holland Consulting home
Contact Holland Consulting
since March 18, 2002
$Id: faq-help.html,v 1.18 2010/02/26 03:58:04 nick Exp $