Friday, July 19, 2013

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.
Author: Keith Johnson


Prasant Saxsena said...

I like your tips, your technical writing are good for improvement in writing and management of technical documents.

Content Writing Services

alina mark said...

We have read the blog and it's a nice thing in your blog. Really helpful with the information provided.Thank you for the post.. For more information visit:- technical writing services UK