Ten Great Technical Writing Tips
Posted March 21, 2008 in Writing 23 Comments »
Technical writing is a skill that will not only help you to better understand a software or system that you are working with, but also will help you to build credibility before others in an organization, especially as a knowledge expert regarding the topic or areas you are covering in your documentation. Here are ten tips for improving your technical writing skills, and these may be applied to not only software, but also to internal processes and procedures that define how a company operates:
- Identify your writing goal. Many times when someone is explaining a system or a software functionality, he or she gets lost in the details of the system and the reader is not able to assimilate the details with the final goal of the documentation you are writing. Stay focused, and if you need, include a comment or two reminding the user of their final goal in reading the documentation.
- Keep screen shots small. Sometimes, technical writers or support personnel capture a whole screen when there is only a part of the screen that needs capturing. This will help the reader to assimilate the button or field you are discussing with the screen.
- Explain, explain, explain! Many times, technical writers explain an idea without a tangible example. Examples always help the reader to assimilate the lesson/idea with the practical use of the software or system. There is nothing more frustrating than reading text that has seemingly no relevance to the system.
- Realize that your reader is not an expert. The majority of people reading documentation will not be system or software experts. That is why they are reading the documentation! The ones who really know the system will navigate without the written words. So, be clear in your explanations, taking the reader by the hand as much as possible.
- Repeat if you must. As you explain a system or software, there may be aspects that must be re-mentioned for the reader to successfully assimilate the current idea with the idea base you have been building all along in your write-up.
- Tables Rock. I especially appreciate a technical writer who can summarize fields or related processes and procedures in a table. This is a good visual way for the reader to further understand the document, using relative comparison, in the form of a table.
- Use sufficient margins in your pages. Do not create a document with narrow margins, because when it comes time to publish, there could be issues related to creating PDFs or even web pages (HTML), so use ample margins.
- Quote & note your sources. Make sure you create a document that reveals sources that are authorities on the matter and that are recognized in a field.
- Don’t be afraid to ask both technical and non-technical personnel review your work. It is good to see the perspectives of readers from both the technical and non-technical aspects of a business.
- Proofread your work, always! There is nothing more embarrassing than submitting work that has typos or other obvious grammatical or structural problems. After writing a document, take a fifteen minute break, then return to the document with a fresh perspective.
Keith
******
About the author: Keith Johnson is a Technical Writer from South Florida who has more than ten years of experience documenting software and business systems. Outside of the office, Keith enjoys practicing affirmations and meditation to relax. He has written a book on each of these subjects. The books are available at the following websites: Great Affirmations and Sacred Syllable
About the author: Keith Johnson is a Technical Writer from South Florida who has more than ten years of experience documenting software and business systems. Outside of the office, Keith enjoys practicing affirmations and meditation to relax. He has written a book on each of these subjects. The books are available at the following websites: Great Affirmations and Sacred Syllable
-
Let’s face it, most of us freelancers do what we do in order to have the potential to work and…
[Read More...] -
Our first Getting Started Guide is now available!
[Read More...]
In this first guide, the talented freelance writer Laura Spencer guides you…
The Unlimited Freelancer is Now Only $19
Unleash the true potential of your business. Get The Unlimited Freelancer and start transforming your freelance business,
now only $19.
Try searching "Getting Clients" or "Productivity"
FreelanceCommunity
Free Resource: Massive Web UI and Button Set
This is a free photoshop set provided by MediaLoot with hundreds of free buttons, boxes, and other useful web elements.5 Fresh and Useful jQuery Plugins Were Born in November 2009
In November 2009, 5 jQuery plugins were born that are new and useful for web designers. Read this post to learn more.How Well Do You Understand CSS Positioning?
The css position property seems easy to grasp, but it works a little differently than it appears on the surface.
Free Report
Sign up for our product discount list to get a free copy of Why Some Freelancers Thrive and Others Barely Survive. You can unsubscribe anytime.
Popular Articles
- SEO Techniques All Top Websites Should Use
- When a Client Can't Afford You: Why It's Still Better to Bid High
- How To Stop Scrambling For Clients And Get A Steady Stream Of Paying Gigs
- A Simple Way To Stop Clients From Rejecting Your Proposals
- 3 Reasons Your Rates Are Still Low (And How To Start Raising Them)
23 Comments
Ritu
March 21st, 2008 at 2:57 pmExcellent advice Keith. You have laid out some great and valid points on this post.
Debra Dalgleish
March 21st, 2008 at 4:09 pmGood points, and your article would have been better without the typo, e.g. “proofread you work”. ;-)
Jon Phillips
March 21st, 2008 at 4:18 pmHey Debra, thanks for pointing it out, I edited the post (happens sometimes, we’re human hehe) :)
Ritu
March 21st, 2008 at 4:22 pmI think the typo was intentional to show that proofreading is critical ;-)
Jon Phillips
March 21st, 2008 at 4:28 pmThier was a typos? :)
Christine OKelly
March 21st, 2008 at 5:07 pmGreat points – I find technical writing to be much more difficult when I know the subject too well. It’s often so much easier to write a technical piece for something that I have to learn about in order to write it.
I’ve been trying to write some more technical ‘how to’s’ lately and have been a little bit stuck trying to get my mind back to the place I was at before these processes became second nature! I like your point about having non-technical readers review it first – that’s huge.
Sterling Okura | bizlift blog
March 21st, 2008 at 5:42 pmI think step 9 is critical. In some of the open-source software I use, the screens and documentation look like they were written by engineers for engineers. It really helps to have a layperson review it and give feedback.
Debra Dalgleish
March 21st, 2008 at 6:17 pmHey Jon, you’re welcome, and I see you fixed #1 too. ;-)
And that’s the most important tip, IMHO.
Jon Phillips
March 21st, 2008 at 6:35 pmHi Debra, no prob! :)
#1 is very good, though being a designer I couldn’t help but smile when I read #7
Hamilton
March 22nd, 2008 at 1:46 amGreat post. I especially like number 7 and number 1. Especially in longer documents its important to keep re-orienting the reader with small summaries. It saves them from getting lost and from having to flip around in the document thereby losing any momentum of flow your writing had created.
Tejvan Pettinger
March 22nd, 2008 at 3:01 amGood article, I think the advice also has some relevance for non technical articles as well
Debra Dalgleish
March 22nd, 2008 at 9:02 amJon, I can see why #7 would make a designer smile. It’s a good layout tip, but not going to help my technical writing skills.
Keith Johnson, Author "Ten Great Technical Writing Tips"
March 22nd, 2008 at 9:20 amThank you, everyone, for visiting freelancefolder dot com and taking the time to comment on my article. I hope that you all will benefit from the article in some way and be able to translate this new knowledge into new productivity, whether it be for personal or professional ends. All The Best, Keith
M.Osita Nwaneri
March 22nd, 2008 at 8:28 pmThanks for this. Certainly spot on.
Stefanie
March 24th, 2008 at 12:58 pmAs solid as these tips are, I have to wonder if they’d help the kind of person who typically does technical writing. I’ve talked to people who write horrible technical explanations and they nearly always think they’re being incredibly simplistic and clear.
Bill Gruener
March 26th, 2008 at 4:41 pmVery good advice! I’ll strengthen tip # 6–tables rock. I use tables a lot, and every time I structure information into a table, I get plaudits. Tables are an excellent structure for paring down the content. By focusing on the absolute, you provide the reader with the info they absolutely need.
Another tip: Grab a style guide. There are many available. The Chicago Manual of Style (CMS) is the classic for most style issues if book oriented. The Microsoft Manual of Style for Technical Publications, Third Edition is excellent for software, Web, anything computer related.
Rebecca
April 25th, 2008 at 1:45 pmTechnical writing differs from print in that people will not read word for word and will be grabbed by different things. It is still important to remember good sentence structure and proper grammar when writing in order to establish credibility. Visit this blog that talks about Top Ten Tip to Better Writing. http://www.prwriterextraordinaire.com/blog.html
Jagdeep
May 16th, 2008 at 12:55 amI would liek to add to the useful information already shared: “Make continuous attempts to write to-the-point instructions that do not rely on heavy vocabulary. You do not want your readers to repeatedly refer to a dictionary while understanding the technical content. Flowery language is intriguing in novels, not in technical documentation.”
Trackbacks