WriterLiz, LLC
  • Home
  • Services
    • Copywriting
    • Websites & SEO
    • Blogs & Articles
    • Technical Writing
    • Medical Writing
    • Training
    • Photography
  • Testimonials
  • Portfolio
  • Clients
  • About
    • About Elizabeth
    • Formal Resume
  • FAQs
  • Blog
  • Projects
  • Personal Creative Work
  • Contact Me

Blog

What makes for good technical writing?

11/5/2009

0 Comments

 
So you want to be a good technical writer.  Ok.  But what does that entail?  What is good technical writing vs. bad technical writing?

I’ve seen a lot of software engineers attempt to write help documentation.  And a lot of companies try to save on cost by having them do so (not a good idea).  During my career I have learned something very important: technical writing is a skill that must be developed, and not everyone is capable of good technical writing.  And something else I have learned: you need to be a good writer, first and foremost, before you can be a good technical writer.  You must have the skills to not only translate technically challenging information into common language, but to use the English language appropriately in pursuit of this goal.

So how can you become a better technical writer?  Or better yet, want to know some technical writing basics?  Here are some tips.

1.  Know your audience.  Are your end users technically savvy people?  Or are computers completely foreign to them? 

Knowing the answer to this question is important for determining how you need to present your material, and what level of detail you should provide.  If you have a very savvy audience, then you can use more complex ideas and omit some basic information (such as, what a user name is).  If you have a group of users who have never before accessed a computer, then you would need to go into more detail about basic use (i.e., explaining what a user name is) and you would want to omit information that is way above their knowledge level.

2.  Use direct language.  Tell them what to do.  Use “click here to continue” rather than “the button should be clicked to continue”.

3.  Get to the point.  The worst technical documents are wordy, wordy, wordy.  Good technical writers know how to condense their material into the shortest possible sentence/paragraph without losing meaning.  This is not always an easy task, depending on your skill level.  But do make an effort.  For example:

Bad technical writing:  Scroll to the bottom of the page and locate the Submit button, which you will then click to submit your information to the database.

Good technical writing:  Click the Submit button at the bottom of the page to submit your information to the database.

What’s so bad about the first example?  Wordy, bumbling, and indirect (“which you will then click”).  What’s so good about the second example?  Clear, to the point, and succinct. 

You don’t need to tell the user to scroll down if you say that the button is at the bottom of the page.  The user will know they need to scroll in order to get there.  So take it out – it’s a waste of space and words.

More tips to come.
0 Comments

Your comment will be posted after it is approved.


Leave a Reply.

    Contact me at info@writerliz.com.

    Welcome to my blog.  Please use the Category links below to find topics of interest to you, or just scroll through current postings.
    Share

    RSS Feed

    Receive new postings via email:

    Enter your email address:

    Delivered by FeedBurner

    Categories

    All
    General Writing Tips
    Grammar Mistakes
    Hiring A Writer
    Marketing
    Money Matters
    Nonprofits
    Starting A Business
    Starting A Business
    Technical Writing
    Training/instructional Design
    Websites And Content

    Archives

    November 2014
    June 2014
    May 2014
    April 2014
    March 2014
    January 2014
    December 2013
    November 2013
    October 2013
    September 2013
    August 2013
    July 2013
    May 2013
    June 2011
    April 2011
    March 2011
    February 2011
    January 2011
    November 2009

Powered by Create your own unique website with customizable templates.
  • Home
  • Services
    • Copywriting
    • Websites & SEO
    • Blogs & Articles
    • Technical Writing
    • Medical Writing
    • Training
    • Photography
  • Testimonials
  • Portfolio
  • Clients
  • About
    • About Elizabeth
    • Formal Resume
  • FAQs
  • Blog
  • Projects
  • Personal Creative Work
  • Contact Me