Author: Dylan Benito

How to Write Technical Documents

How to write technical documents first depends on the kind of technical document you’re writing. This is the biggest factor in deciding tone, style, word usage, etc. Most of the technical documents I write are user guides (UG), or Best Known Methods (BKM). Both types of documents save your reader’s time and energy, and can make the difference when launching a product or training session.

How to Write User Guides/Manuals


User Guides or Manuals (UM), tend to be longer, more complicated, and have more references. They generally deal with product specs, building instructions, and the like. The longest UG I have worked on was over 4,000 pages, the shortest are less than ten. They all follow the same basic steps:

  • Introduction
  • Body of the Text
    • Tools Needed (if applicable)
    • Steps (usually with Images)
    • Final results
  • Conclusion
  • Appendix with resources (if applicable)

Then it is up to you, the writer, to take all that information that you have tested, or have been given, and make it into something that the end user is able to read.

How do you do that? You KISS* (Keep it Simple, Scribe**). Think about who your audience is, a skill that is always important when writing. When I write, I imagine that I am producing documents for my grandparents or my friends who are ESL speakers (English as a Second Language). English is a tricky language, and a technical document is complicated enough without translation issues. Avoid turns of phrase and spell out all acronyms the first time they are introduced. Don’t take for granted the things that you know, they may not apply in a different language.

Another neat thing about writing UG/UMs is the fact that you can get away with publishing a whole document without a single complete sentence. In fact, bullet points, numbered lists, and notes are your friends in technical documentation. Bring on the sentence fragments! Use tables and images to illustrate the instructions. This is a situation where a picture is really worth a thousand words, and visuals are easier to understand.

When it comes down to it, the document is a more detailed version of “put the thing in the other thing and turn it on,” or some variation of that idea. If you can get that message across to the users, you’ve done your job.

How to Write Best Known Methods/Internal Processes


I find that BKMs are easier to write. Usually, when you’re writing a BKM it is for an internal process that you work on regularly. Examples of BKMs are: instructions on posting a document to an internal portal, how to run a machine, or how to process software testing. Even if it isn’t something that you work on personally, you should work closely enough with the person giving you the instructions to complete the final project. If you feel like you don’t have enough information, talk with your manager/engineer to fill in the blanks.

BKMs work best with clear instructions, small words (unless they are process specific), and diagrams. Think about trying to put IKEA furniture together without the diagrams. My house would be filled with nightmarish semblances of furniture. These documents are often shorter than a UG, usually less than ten pages. The writing process is very similar:

  • Quick introduction, less than a paragraph.
  • Steps for the process, including sub-steps, diagrams, tools needed, and images.
  • Conclusion/Summary of the final product.

Right now you may be wondering what the difference is between a User Guide and a BKM, which is understandable as they are similar. Think of a User Guide as the full explanation and possibly a little history of the project, whereas a BKM is a quick “how to.” Essentially, the two documents cover the same basic ideas, but the detail they get into differs. Remember: always keep your audience in mind. User Guides often go to external users (a wider audience) and BKMs tend to be internal (a smaller audience).

Final Tips and Notes


Technical writing is much like any other style of writing; you are passing along information to your readers in the clearest way possible.

  • Bullets, notes, and number lists are your friends.
  • Add images whenever applicable, the entire document can be images with minor text notes if that’s what works.
  • Keep your audience’s technical knowledge in mind.
  • Spell out acronyms the first time they are used, and consider adding a table of acronyms if the document contains more than ten.
  • Use tables to keep track of test results.
  • Don’t get fancy with your language. The document needs to be readable, not pretty.
  • Commit to a positive relationship with your engineers/testers, this will make your job so much easier. Tech guys tend to like cookies, just an FYI.
  • Most of all have fun with it. Even technical writing can be enjoyable if you keep an open mind. Proof-positive: I love my job.

*Tech Writers LOVE acronyms, seriously we can have whole conversations in them.
**Traditionally, this ends with Stupid, but I think that’s rude and ablest.

5 Tips to Help You Enjoy Networking Events

One of the things that I hear from other freelancers is how hard networking is. And it seems that writers are even more prone to this idea. In fact, I used to think the same thing. I hated the idea of getting out and meeting new people. The idea of having to tell people about what I did, and why they might want to part with some of their hard earned dollars, or asking other freelancers if they knew of potential clients? Forget about it. It was the last thing I wanted to do.

So, what changed? This week, I have two evenings devoted to networking and I am looking forward to both of them. I really noticed the change after an event I attended a few weeks ago. I have to say, a big part of my enjoyment comes from the events I’m attending. I have been doing this long enough that I know a great group of people, though this isn’t necessary for good networking. Through those connections, I have found events that are fun and productive. Which is exactly what you want.

Here are a five tips that may help you enjoy networking events:

  1. Go with a good friend or colleague the first time or two.

    That way, if you start to feel lost or overwhelmed you will have a familiar face to talk to. Your friend might even do the talking and introduce you to great people!

  2. Take business cards!

    I cannot stress this enough and I am notorious for going to events without cards. Amazing opportunities can, and will happen. Make sure people have a way to contact you. I’m going to put more in my bag right now. Really.

  3. Take a notebook and write down ideas that pop up as you network.

    A conversation could be a great jumping off point for a new project. You can also write down your impressions of other people and your ideas about future collaboration.

  4. Go to events that sound interesting to you.

    This is really important. I started going to the PDX WIIT (Women in Information Technology) events last summer and they are a blast! I have mentioned them to some of my other writer friends and got, “Meh.” back. That’s totally okay. More geeky tech events for me. Point: Find information you love.

  5. Try to have fun.

    I know this is a cheesy one, but if you go with the idea that the event is going to suck…it probably will. Even if you can’t have fun, remind yourself that this is a great way to connect with like-minded people, and could land you a job. It’s hard to go wrong with either of those.

You all might be wondering what networking events I go to on a regular basis that are so cool. I have another list for you. What can I say? I’m a technical writer.

 

  • My professional writing group, the Copywriter Conclave of Portland, has a monthly meeting and happy hour. You can email membership@portlandcopywriters.com for time and location. (We’re hosting a Resume Design for Non-Designers workshop on April 23rd, by the way. You should come!)

  • The Freelancers Union hosts a happy hour every month at the Green Dragon. This is a super fun, really great for networking, positive event. By the time this posts, April’s event will have passed, but I look forward to seeing you all in May.

  • The Freelancers Union also hosts workshops on a monthly basis. Check out their calendar for more information.

  • PDX WIIT has events regularly. I recommend following them on Twitter or LinkedIn for specific events.

  • And, finally, a quick Google search of Portland Freelance Mixers/Events will lead you to many more, literally, like four million more.

I hope this will help ease some of the stress that can come along with thinking about putting yourself out there. And I hope to see many more people at future events.

On-Site Freelancing Can Cure Loneliness

Freelancing has many plusses: Setting your own schedule, working a job you love (where you get to be the boss), setting your own hourly rate, and many, many more perks. One of the things that people do find to complain about is the lack of work companionship. This lack of work-friends sends many a freelancer to seek out writing groups like CC: PDX, and we are quite happy about that. Freelancers tend to come together in shared offices, too. Portland has a number of shared spaces, and if the Conclave gets its way, we will have our own space in the future. We all like the idea of pooling resources, and having a place to collaborate without having to “go to the office,” something that most freelancers dread the idea of.

Freelancing has many twists and turns. I was fortunate to get a long-term contract last year, mostly on-site. It made me feel like I was going back on some of the basic tenants of freelancing; I would be working for someone again. One of the things I was looking forward to was being on a team again. I really enjoy working with people; it was always one of the things I liked most about working in restaurants and bookstores. There were times where personalities clashed, but there was always room for growth and understanding.

I had some anxiety about going into an office style workspace, especially one that was so technical (I’m a technical writer, and this is a big company). I am a little, well; I don’t exactly fit into the traditional office environment. To calm myself down, I did a little research and came across an image that really resonated with me. I feel like it applies to freelancing and the more traditional office space working relationships. At any rate, it made me feel better about sitting in an office with the same people day after day.

Neil Gaimanfreelance venn

The idea comes from author, Neil Gaiman’s University of Arts commencement speech. I try to adhere to all three circles, but if I had to choose two categories, as Neil Gaiman suggests most people fall into, they would be: I do good work and I’m nice. I tend to get lost frequently, so being on time is something that I slip up on. I might have a tendency to get distracted by projects and lose track of time too, maybe.

Mr. Gaiman says,

You get work however you get work. People keep working in a freelance world — and more and more of today’s world is freelance — because their work is good, and because they are easy to get along with, and because they deliver the work on time. And you don’t even need all three. Two out of three is fine. People will tolerate how unpleasant you are if your work is good and you deliver it on time. They’ll forgive the lateness of the work if it’s good, and if they like you. And you don’t have to be as good as the others if you’re on time and it’s always a pleasure to hear from you.

It was this bit of advice that I took to heart going into my on-site office job, and I have incorporated it into my freelance work.

A last bit of advice from Neil Gaiman, “Go out and make good art.” It seems to me, that anyone looking to break into the freelance world can take these ideas into consideration. If you work onsite, in your home, in a shared office, or however you work, make good art (work), be nice, and be as on time as possible. I guarantee it will make your work life easier.