Skip to main content
Welcome guest. | Register | Login | Post

How To Write Tech Docs

21 replies [Last post]
supermike's picture
Offline
Joined: 2006-02-17

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?

libervisco's picture
Offline
Joined: 2006-05-04

This is an awesome guide supermike! I will link to it as recommended guidelines for the writers team on Nuxified.org. It also deserves a sticky in an articles forum.

"supermike" wrote:

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.

If you remove that sentence and just say something like "here's a quick tutorial on how to write tech docs" then I think we can send this to digg and other site. I really think it's worth it!

I also encourage you to consider joining the writers team officially, since you're already doing the good job with it. Smiling

Thanks
Daniel

supermike's picture
Offline
Joined: 2006-02-17

I think it needs more beef and a better layout. I'm looking forward to critical feedback and those with more advice. For instance, I think words should be said about:

* Understanding audience
* Understanding tone
* Ethics -- The risk of telling people how to do something dangerous or extremely risky, and without proper warning, such as how to change their monitor refresh rate improperly (which could cause fire), or a command to slow their processor fan way down (which could cause fire), etc.

But I want to keep it short. So I'm going to revise and find a happy median between long and short.

libervisco's picture
Offline
Joined: 2006-05-04

Oh alright then. Smiling

I'll just take it off the homepage until it is revised and ready. I'll leave it in this forum though.

Thanks

supermike's picture
Offline
Joined: 2006-02-17

* Watch out for huge mixups like "then" and "than", "except" and "accept".

* Watch out for misspelling "similar" as you would familiar, like "similiar", and vice-versa with "familar".

* Avoid double negatives like "He does not seek money for the project no more than he seeks fame."

* As you grow more functional in writing, you'll learn that you can replace certain phrases with shorter phrases. For example, "On the following day when you reboot your system, you'll notice..." can be "Rebooting on the next day, you'll notice...." Sometimes it's as simple as dropping words out like "when". Be careful though because sometimes this makes for unpleasant reading, lacking flow, taken too an extreme.

supermike's picture
Offline
Joined: 2006-02-17

* Know your audience. Before you write, think to whom you are writing. Write it out on paper. Picture it. Never stray from it. For instance, if I'm writing to intermediate techs, then these are people who can appreciate docs with humor and as long as it's not too fun -- they do appreciate maturity. They also can get turned off by newbie kinds of discussions.

* Watch out for edits where you cut off and forget a. (Word or phrase!) By the way, I do this often.

* Know your tone. Does it sound pschitzophrenic (has one kind of tone in one sense and then has another tone later on)? You'll want to avoid that. Is it also too condescending or perhaps rude. Often a friend can help you read this and see this.

* Know the proper way to use "who" and "whom". As you write and see these words, in your mind you should replace these with "he" and "him" to know which ones should be used. For instance, "If you remember to whom you gave that document, then..." And if that doesn't help, then consider that if it follows a preposition, then it most likely, but not always, will be the "whom" variety instead of "who".

* Don't forget to continue a consistent verb tense (having instead have, for instance), depending on which one you choose.

* Don't forget to continue a consistent person/point of view. If you refer to your reader as "you", don't switch it to "we" or "they". Also note that I would avoid using antiquated references to point of view such as "the author" (when referring to you) and "the reader" (when referring to them). It's funny how often I still read that and I think that is so old-school, man. Instead, stick with "I" for yourself, and "you", "we", or "one" for your reader. Not also that even "one" in some cases can seem antiquated and you should consider replacing that if you think it really starts to sound like an old book. This person/point of view is also important when used in providing examples, where you might need to intentionally stray from the current point of view and into the view of the example. In this kind of example, you might, for instance, switch to saying "he", "they", etc. instead of "you".

* Avoid BTW for By The Way, and other "chat room acronyms". Not everyone gets it, even still, oddly enough. Keep that for forum messages and emails, not tech docs.

* Be careful when you use quotes about something someone said -- it could come back to seriously bite you, perhaps even with a legal issue or an embarassing retort from that person in the media or on the web. Instead, ask for their permission first! In some cases, and even this is a bit "iffy" territory, you can take famous people and paraphrase what you think they meant, but you need to state that this is your interpretation of it when possible. That's not always possible. It depends on whether you properly grasped what the person said and whether this is a controversial or negative topic. And if you can avoid quoting or paraphrasing someone without hurting your piece, then do so. And if it's in reference to Bill Gates, well, everyone jumps on his case, so you can do whatever you want. (I never said that!)

supermike's picture
Offline
Joined: 2006-02-17

* Imagine someone lording over you when you write, occasionally saying, "Shut up already! I get the point!", "Huh? You've lost me.", "That don't make no kinda sense.", and "ZZZzzzzz. I'm sorry, did you finally get to the conclusion?" That's what I do. It's a big help.

libervisco's picture
Offline
Joined: 2006-05-04

Now that you're within a team, what about moving this in a writers team forum (private) since it's a draft and noone but me has yet replied anyway?

After it is done it can be republished as a whole in the articles section.

Just a suggestion.

"supermike" wrote:

Be careful when you use quotes about something someone said -- it could come back to seriously bite you, perhaps even with a legal issue or an embarassing retort from that person in the media or on the web. Instead, ask for their permission first!

Agreed. But I'd just like to note that in some cases permision is already there if the text you're quoting is released under a license that gives permission (such as Creative Commons - Attribution - ShareAlike for example).

supermike's picture
Offline
Joined: 2006-02-17

Sure, move the doc. I'm looking for a collaborator on the doc this time. This one is going to be tough but could get us a lot of recognition, I feel, if it is concise. I think it gives a fresh, modern perspective on web publishing of tech material that you don't often hear. For instance, I think web publishing has come to a point where people except truncations of words such as "doc", "tech", etc., and we can start to show our excitement, to have fun with this, and use phrases like, "Kicking", "Snap!", etc. It's like "Tech Docs for the Web 2.0".

BTW, I'm not a fan of the "IP" link in the messages. Sometimes I write from my day job office and that's something I want to cloak, for obvious reasons. If you provide it at all, perhaps you could have a preference to turn that off for our profiles, and by default it is on.

And now I see these red, yellow, and blue square buttons on the forum msgs -- I don't know what these do. Permanently ban someone? I imagine you're experimenting, right?

libervisco's picture
Offline
Joined: 2006-05-04
"supermike" wrote:

Sure, move the doc. I'm looking for a collaborator on the doc this time. This one is going to be tough but could get us a lot of recognition, I feel, if it is concise. I think it gives a fresh, modern perspective on web publishing of tech material that you don't often hear. For instance, I think web publishing has come to a point where people except truncations of words such as "doc", "tech", etc., and we can start to show our excitement, to have fun with this, and use phrases like, "Kicking", "Snap!", etc. It's like "Tech Docs for the Web 2.0".

Hehe well indeed.. The style changes and I definitely don't think there's a reason for us to stay cubed in an old style writing. I'm not an expert with this stuff, but I can help how I can, by giving some suggestions and such. But I think you're already doing a great job with it on your own. Maybe someone else from the team can help too.

"supermike" wrote:

BTW, I'm not a fan of the "IP" link in the messages. Sometimes I write from my day job office and that's something I want to cloak, for obvious reasons. If you provide it at all, perhaps you could have a preference to turn that off for our profiles, and by default it is on.

Those are visible only to the moderators and since the content team has been given ability to moderate the "writers team" forum you can see it here too. The IP information is secret though as in not accessible publically. As moderators are chosen by trust I don't think there can be any abuse going on.

I actually barely ever look at those IPs. The purpose of these is rather obvious. It is here in case someone starts messing around with the forums (which is unlikely, especially now, but not impossible in the future). It's merely a preventive measure. I haven't put that in myself though. It is a built in feature of phpbb.

I'm not sure if it can be turned off per user though. I'll have to check that. If yes I can turn it off for you since I know you're not an abuser anyway.

"supermike" wrote:

And now I see these red, yellow, and blue square buttons on the forum msgs -- I don't know what these do. Permanently ban someone? I imagine you're experimenting, right?

Those features came with phpbb2 plus. They're also restricted for use by moderators only for the purpose of dealing with abusers (if there every will be ones). The yellow card issues a warning, red bans the user, green unbans them and blue issues a warning about a certain post for other mods to deal with (or admin). That pretty much resembles the IRC moderation features.

I'm not experimenting though. I haven't even touched all of these buttons till you mentioned them now. I just pressed them to see what message they bring to see what they do. Smiling

There should really be nothing to worry about. Some moderation features ought to exist, though for Libervis Network sites they're very rarely used for taking any harsher measures. So far I've never had to ban a user for abuse except deleting obvious spammers (or spambots).

a thing's picture
Offline
Joined: 2005-12-20

Use analogies.

supermike's picture
Offline
Joined: 2006-02-17

On the ip thing, libervisco, you can leave it on. I didn't know this. Sorry about that. Since it's not public, then great. I too want to block abuse.

supermike's picture
Offline
Joined: 2006-02-17

On the card buttons. Oh, it's a moderator thing. Okay. I get it now. I probably wouldn't have relied solely on color if I were a phpbb developer. I would have made it so that you put your cursor over it and an alt (and title) attribute of the IMG tag would say something like "ban", "warn", "unban", and "moderator flag", or put icons inside to help, visually. But no matter -- most people don't see these, so I can get used to it.

I guess I need to go to moderator school. he he.

Actually, I don't really want to be a moderator. I just want to publish and respond. But if that's the way to make this easy, then so be it.

supermike's picture
Offline
Joined: 2006-02-17

a_thing: Use analogies. Yep, that's a good one to write down.

all: I think I'm going to have to start making an outline at this point, breaking it up into sections, looking to find at least 3 or more points per outline item, and getting a second draft out.

libervisco's picture
Offline
Joined: 2006-05-04
"supermike" wrote:

On the card buttons. Oh, it's a moderator thing. Okay. I get it now. I probably wouldn't have relied solely on color if I were a phpbb developer. I would have made it so that you put your cursor over it and an alt (and title) attribute of the IMG tag would say something like "ban", "warn", "unban", and "moderator flag", or put icons inside to help, visually. But no matter -- most people don't see these, so I can get used to it.

Yeah, actually, but at least when you click it you get a dialog that says what it does and if you're sure you want to do that. If it's too confusing I can might change it to different images or at least add an alt title text to pop on mouseover.

"supermike" wrote:

Actually, I don't really want to be a moderator. I just want to publish and respond. But if that's the way to make this easy, then so be it.

If you guys would like it better I can just leave the moderation to the moderators team. It's not like there's going to be much to moderate here anyway. Hmm.. that could actually make more sense. Mods handle moderation and you handle content. It's easy either way.

libervisco's picture
Offline
Joined: 2006-05-04
"supermike" wrote:

all: I think I'm going to have to start making an outline at this point, breaking it up into sections, looking to find at least 3 or more points per outline item, and getting a second draft out.

Cool. As long as it is a draft though keep it inside this forum. Only finished stuff ready for publishing should go to the articles forum.

Cheers

(really have to go to sleep now) :smt001

AndrewB's picture
Offline
Joined: 2005-12-18
"libervisco" wrote:

If you guys would like it better I can just leave the moderation to the moderators team. It's not like there's going to be much to moderate here anyway. Hmm.. that could actually make more sense. Mods handle moderation and you handle content. It's easy either way.

What does that make me Eye
Im the odd ball that does both!
Tho Im not officially on the writers team.

I would maybe make it, writers can access only writing and stuff.
Mode can access all

AndrewB's picture
Offline
Joined: 2005-12-18
"libervisco" wrote:

(really have to go to sleep now) :smt001

WIMP! Still no sleep yet.
Sleep is inferior.

libervisco's picture
Offline
Joined: 2006-05-04

:mrgreen:

Actually I'm still awake (was reading about the last topic posted on libervis and then making a rather long reply) Eh.. :s

I'm going to sleep now though Laughing out loud

libervisco's picture
Offline
Joined: 2006-05-04
"AndrewB" wrote:

I would maybe make it, writers can access only writing and stuff.
Mode can access all

Exactly. That pretty much answers your question. Laughing out loud

You can join the writers team too though if you wish (and intend to contribute more articles Sticking out tongue ), but I'm not sure how to squeeze both titles in your profile. Laughing

AndrewB's picture
Offline
Joined: 2005-12-18
"libervisco" wrote:
"AndrewB" wrote:

I would maybe make it, writers can access only writing and stuff.
Mode can access all

Exactly. That pretty much answers your question. Laughing out loud

You can join the writers team too though if you wish (and intend to contribute more articles Sticking out tongue ), but I'm not sure how to squeeze both titles in your profile. Laughing

'Know It All'
Would suit fine Sticking out tongue

Nah I dont want to make a commitment that I may not be able to stick to.
I will continue to write freelance, and help out grabbings distro's

libervisco's picture
Offline
Joined: 2006-05-04
I have linked to this guide

I have linked to this guide from the Nuxified contribute page in the "submit an article" section as well as in the note on the article submission page.

I've just printed it and am gonna try incorporate its points in a review I am going to write some time soon. Smiling

Thanks again supermike for writing it!