Software Business

Writing Good Software Documentation

Before Writing

(page 1 of 3)
Published on: November 16, 2006

Writing software documentation may seem extremely easy for some of us, whereas others may consider it one of the most difficult tasks they could ever be asked to do.

The generic term for this kind of writing is "technical writing". A person who does this job is generally referred to as a "technical writer", with quite extensive knowledge of software and technology and with a deeper understanding of the logic behind the software, or a "technical writer", a person who, although somewhat overwhelmed by all the denominations and the algorithms of the software, is accurate in producing a proper technical text.

Nevertheless, regardless of the orientation of the writers, be them more technical than writers, there are some things that need to be considered before, during and after the writing process.

Before Writing

  • Know the Software

    • Training
      Make sure you receive proper training for the software that you are about to document and that you have the software explained to you, step by step.
    • Experiment
      Have the software installed on your machine; make sure you also have access to as musch as possible of the necessary software related information, and that you have access to all the functionalities of the software. Explore all its functions, and don't be afraid to ask the engineers whenever you are not certain about the influence of, let's say, an unchecked checkbox or radio button on the process thatyou are documenting. Don't assume anything, you could be wrong.
    • Gather information
      This may mean older documents, definition documents for certain functionalities or specifications, general PowerPoint presentations, marketing documents, etc. They may help you along the way.
  • Identify the Target Audience


    • This is of utmost importance. You have to know beforehand what kind of public the document you are about to produce addresses to, so that you know how to adjust and adapt the style and the informational content of the document. Again, ask the engineers, the product managers, about the audience. You don't want to be too technical for a non-technical audience, or vice versa.

    Article Pages

    Articles & Interviews RSS Feed Subscribe to our RSS Feed
    Subscribe to our Newsletter Subscribe to our Newsletter
    Rate article
    Comments (2)
    Neha says:
    July 15th, 2008 at 9:19 am

    I deem its a great article. Helped me quite alot.
    Prabu R says:
    March 16th, 2009 at 8:13 pm

    Quite an awesome resource. Helped me put together a checklist. Thank you, folks!

    Leave a comment

    Name *
    Mail(will not be published) *
    Website *
    Subscribe to comments:
    Validation Code *:       
    Please note: Comment moderation is enabled and may delay your comment. There is no need to resubmit your comment.

    Copyright ® 2010, http://www.avangate.com all rights reserved.
    This article may be reproduced in a website, e-zine, CD-ROM, book, magazine, etc. so long as the above information is included in full, including the link back to this website. Please e-mail at articles@avangate.com , before using the article.