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 "why??". 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 page!). 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. vi(1) and mg(1) work nicely. 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 grammar checker.

Priorities

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
Spelling
Grammar

NOT Priorities

Some things just are NOT priorities to me.

Man page links just because the word occurs in the man pages. 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 http://validator.w3.org's 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 team.

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 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.
- is preferred to 
- is preferred to 
etc. Yes, I know, some HTML guides suggest just the opposite. Tough.
Do NOT use closing tags that are not required for HTML compliance, such as 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:
```
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=entry&amp;sektion=number">entry(number)</a>
```
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:
Wrong:
```
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=entry&amp;sektion=number">
entry(number)</a>
```
Right:
```
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=entry&amp;sektion=number"
>entry(number)</a>
```
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 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:

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 system.
Update the faq9 Linux/OpenBSD co-existence info. This is rather difficult, as there are so many Linux variations out there. 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.

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