Tech­ni­cal writ­ing is a skill that will not only help you to bet­ter under­stand a soft­ware or sys­tem that you are work­ing with, but also will help you to build cred­i­bil­ity before oth­ers in an orga­ni­za­tion, espe­cially as a knowl­edge expert regard­ing the topic or areas you are cov­er­ing in your doc­u­men­ta­tion. Here are ten tips for improv­ing your tech­ni­cal writ­ing skills, and these may be applied to not only soft­ware, but also to inter­nal processes and pro­ce­dures that define how a com­pany operates:

  1. Iden­tify your writ­ing goal. Many times when some­one is explain­ing a sys­tem or a soft­ware func­tion­al­ity, he or she gets lost in the details of the sys­tem and the reader is not able to assim­i­late the details with the final goal of the doc­u­men­ta­tion you are writ­ing. Stay focused, and if you need, include a com­ment or two remind­ing the user of their final goal in read­ing the documentation.
  2. Keep screen shots small. Some­times, tech­ni­cal writ­ers or sup­port per­son­nel cap­ture a whole screen when there is only a part of the screen that needs cap­tur­ing. This will help the reader to assim­i­late the but­ton or field you are dis­cussing with the screen.
  3. Explain, explain, explain! Many times, tech­ni­cal writ­ers explain an idea with­out a tan­gi­ble exam­ple. Exam­ples always help the reader to assim­i­late the lesson/idea with the prac­ti­cal use of the soft­ware or sys­tem. There is noth­ing more frus­trat­ing than read­ing text that has seem­ingly no rel­e­vance to the system.
  4. Real­ize that your reader is not an expert. The major­ity of peo­ple read­ing doc­u­men­ta­tion will not be sys­tem or soft­ware experts. That is why they are read­ing the doc­u­men­ta­tion! The ones who really know the sys­tem will nav­i­gate with­out the writ­ten words. So, be clear in your expla­na­tions, tak­ing the reader by the hand as much as possible.
  5. Repeat if you must. As you explain a sys­tem or soft­ware, there may be aspects that must be re-mentioned for the reader to suc­cess­fully assim­i­late the cur­rent idea with the idea base you have been build­ing all along in your write-up.
  6. Tables Rock. I espe­cially appre­ci­ate a tech­ni­cal writer who can sum­ma­rize fields or related processes and pro­ce­dures in a table. This is a good visual way for the reader to fur­ther under­stand the doc­u­ment, using rel­a­tive com­par­i­son, in the form of a table.
  7. Use suf­fi­cient mar­gins in your pages. Do not cre­ate a doc­u­ment with nar­row mar­gins, because when it comes time to pub­lish, there could be issues related to cre­at­ing PDFs or even web pages (HTML), so use ample margins.
  8. Quote & note your sources. Make sure you cre­ate a doc­u­ment that reveals sources that are author­i­ties on the mat­ter and that are rec­og­nized in a field.
  9. Don’t be afraid to ask both tech­ni­cal and non-technical per­son­nel review your work. It is good to see the per­spec­tives of read­ers from both the tech­ni­cal and non-technical aspects of a business.
  10. Proof­read your work, always! There is noth­ing more embar­rass­ing than sub­mit­ting work that has typos or other obvi­ous gram­mat­i­cal or struc­tural prob­lems. After writ­ing a doc­u­ment, take a fif­teen minute break, then return to the doc­u­ment with a fresh perspective.



About the author: Keith John­son is a Tech­ni­cal Writer from South Florida who has more than ten years of expe­ri­ence doc­u­ment­ing soft­ware and busi­ness sys­tems. Out­side of the office, Keith enjoys prac­tic­ing affir­ma­tions and med­i­ta­tion to relax. He has writ­ten a book on each of these sub­jects. The books are avail­able at the fol­low­ing web­sites: Great Affir­ma­tions and Sacred Syl­la­ble