Ten Great Technical Writing Tips
Posted by Keith Johnson
Hi! Seems it's your first visit on Freelance Folder. Welcome! You may want to grab our RSS feed or you can also subscribe and receive updates in your e-mail. So you'd always be up to date! Thanks for visiting!
- 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
19 Rockin' Comments
March 21st, 2008 at 2:57 pm
Excellent advice Keith. You have laid out some great and valid points on this post.
March 21st, 2008 at 4:09 pm
Good points, and your article would have been better without the typo, e.g. “proofread you work”. ;-)
March 21st, 2008 at 4:18 pm
Hey Debra, thanks for pointing it out, I edited the post (happens sometimes, we’re human hehe) :)
March 21st, 2008 at 4:22 pm
I think the typo was intentional to show that proofreading is critical ;-)
March 21st, 2008 at 4:28 pm
Thier was a typos? :)
March 21st, 2008 at 5:07 pm
Great 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.
March 21st, 2008 at 5:42 pm
I 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.
March 21st, 2008 at 6:17 pm
Hey Jon, you’re welcome, and I see you fixed #1 too. ;-)
And that’s the most important tip, IMHO.
March 21st, 2008 at 6:35 pm
Hi Debra, no prob! :)
#1 is very good, though being a designer I couldn’t help but smile when I read #7
March 22nd, 2008 at 1:46 am
Great 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.
March 22nd, 2008 at 3:01 am
Good article, I think the advice also has some relevance for non technical articles as well
March 22nd, 2008 at 9:02 am
Jon, 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.
March 22nd, 2008 at 9:20 am
Thank 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
March 22nd, 2008 at 8:28 pm
Thanks for this. Certainly spot on.
March 24th, 2008 at 12:58 pm
As 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.
March 26th, 2008 at 4:41 pm
Very 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.
April 25th, 2008 at 1:45 pm
Technical 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
Trackbacks
Share your thoughts, leave a comment!