Ten Great Technical Writing Tips

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:

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. 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.
  9. 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.
  10. 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

Comments

  1. says

    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.

  2. says

    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.

  3. says

    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.

  4. says

    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.

  5. Rebecca says

    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

  6. Jagdeep says

    I 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.”

  7. says

    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.

  8. says

    I do have faith in every one of the ideas you could have shown your posting. These are quite persuading all of which will definitely function. Even now, the threads are quite shorter for newbies. May just you want lengthen these a tad coming from pursuing time? Many thanks for your posting.

  9. says

    When I originally commented I clicked the “Notify me when new comments are added” checkbox and now each time a comment is
    added I get four e-mails with the same comment. Is there any
    way you can remove pwople from that service? Bless
    you!

Trackbacks

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>