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.



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