Here's my quickie tutorial on how to write tech docs. Sorry for the loose format here, not making this itself a tech doc, but I'm short on time. I'll make it with bullet points.
* The title evidently means everything. You'll get more eyeballs if someone says, "Wow, that's some title," and decides to click. Drug references like "Roll your own..." seem to catch techies to want to read it. I don't know why that occurs.
* Have fun with it sometimes. If you don't go overboard, occasionally show your excitement. Use words like "kicking" and other new hip, made-up words like "Snap!" It makes it a joy to read sometimes.
* Write your concept out first, then outline, then write from scratch again, using only your best phrases and your key thoughts.
* Get over the hump of being afraid to write. I used to have that. It's a dumb feeling. You talk with others, don't you? They don't sit there looking confused all the time, do they? Then just write like you talk, then outline from that, then edit the mess out of it, run it by a companion, and publish. Better to publish and take feedback from it and adjust then to not publish at all.
* You don't have to be an English language pro. I have a degree in English and I still make mistakes. Use the help of others to read your stuff and give advice. Most often your own brain knows when it's improper English (unless you rarely speak English). If you re-read a sentence slowly after about 2 days and your brain says, "Wait a minute, I'm having to slow down here," or "Wait a minute, I don't get your point," or "Wait a minute, I don't see how these things connect or why you chose this word," then you more than likely have made a logic error or a grammar error. But again, check with your pals.
* After you write something, learn from the feedback. Praise your readers -- don't jump their case. When they call you to the mat on something, you have to stand back and look at it objectively. If they were right and you were wrong, then tell them thank you and that you accept that. They'll appreciate that a lot more. It takes a level of maturity here for this.
* You're writing a tech doc for the web to be read by techies. You can invent words sometimes, truncate words (like "doc"), or use "But" and "And" to begin a sentence sometimes when it just flows better than having to put the more formal "However", "Moreover", and "Essentially" all the time. Sure, your English teacher may shoot you, but people will love how passionate and user-friendly the doc sounds.
* I don't recommend you split an infinitive or end with a preposition. Forget what your English teacher says about it. We know she wants to tell you more about how this is grammatically incorrect. All you need to know is that It causes for confusing reading.
* Don't be afraid to use an em dash occasionally -- sometimes that's how we think when we say something and then stand back to say it another way.
* You're going to need a short background intro that draws people in without boring them to death. They need to know within the first three sentences what's in it for them and why they should care to read your stuff.
* You're going to need a conclusion that wraps up what you said in case they didn't get it. This is so that, if they skimmed and missed something, they might go back and read it again.
* If you have a process they should follow, use numbered or outlined steps instead of bullets.
* Use bullets when you need to do this. Tech docs use this all the time.
* If you're writing for noobs, then up front you're going to want to point them somewhere else if they don't understand some basic terms and acronyms that you will depend on throughout the doc. If you plan on giving them a primer on some of these terms and acronyms within your doc, then bless you, but sometimes that can get too out of hand and away from your point. For instance, if I had to describe to someone what TCP meant in great detail before I started talking about a firewall doc, I might be about 15 paragraphs into that before I get back to my point about firewalls. And that, my friend, is way too distracting to be worth your while.
* If you're writing for intermediates or advanced users, then up front you're going to want to point them somewhere else if they don't understand at least some more intermediate concepts.
* Realize when you're trailing off with the point and make that either a separate doc or is beyond the scope. Sometimes it is important to cover an item marginally, however, and then say something to the effect that it is another thread for another day or is beyond scope of this document.
* The ideal tech doc on the web is about 12 to 15 paragraphs before people start to doze off. However, you could do what I did. Your first doc could go into a lot of detail and be something like 24 paragraphs. Then, release it after you've run it by friends. Later on, if you feel like revising it, go back and see if you can edit it down to 12 paragraphs or as close to that number as possible.
* Every 3 to 5 sentences, ask yourself, "Does this need a section heading to help skimmers?" If it does, then give it a section heading like, "V. TESTING - CALLING THE SCRIPT". I like to use ALL CAPS because I want to catch the skimmers eyes even more. I *always* skim on the web.
* Does it have anything derogatory, condescending, or uncool in it, and this is not an editorial? Then cut it.
* I don't recommend building up to something in your doc so that by the second to last paragraph, they have finally achieved something. You may lose their attention. Give them a short example at first to pump up their excitement, and then give them a larger example after that which completes the task.
* Consider whether you need a "Getting Started", "Configuring", and a "Testing" section. I most often need these.
* Watch out for homophones. I have this problem all the time. Words like "write" and "right" are common problems, for instance.
* Avoid overuse of the comma or especially wordy sentences. However, avoid overly small sentences too when you can. The short sentences, if abused, are too distracting. Note also that a comma is not used for a pause in breath, but has a proper grammar use.
* Yes, you're going to need to spell-check your doc.
Anyone got anymore bullet points?
), but I'm not sure how to squeeze both titles in your profile. 
Joined: 2006-02-17