If you're new here, you may want to subscribe to my RSS feed. Thanks for visiting!

One of the most common sayings I have had to endure as a Technical Writer is that documentation is considered by software companies to be a “necessary evil”. Is that really the case? Well, let’s take a close look at the positive and negative aspects of documentation and see if this saying is correct or not.

Positive Aspects of Software Documentation

1. System Documentation can be established to help programmers make sense of code written by someone else previously, usually for another module or version.

2. System Documentation is generated by a tool and not a person, so usually it comes out pretty good and also is easy to read and understand. Object oriented programming, generated by a good system documentation tool, translates into really beautiful inheritance diagrams and drive down menus with classes, explanations and more.

3. User Documentation helps end-users to navigate successfully through the different options that the program has to offer. Sometimes the apparent functionality of the program is not easily understood, but with good documentation, putting the program to work becomes remarkably easy.

4. User Documentation helps in the testing of the software product, because as users are increasing their skills with the program, they will also be doing all sorts of unexpected things, and this is the best way for the vendor to see if the program was coded well.

5. Architecture Documentation helps architects and also development managers to see the high-level and intuitive aspects of the software, before coding actually happens. This is a great means to clear up any roadblocks at the system level - that is - servers or systems communicating with one another.

6. Testing Documentation helps people in Quality Assurance to identify and execute very exact tasks that call into question specific coding tasks previously assigned to programmers. Did development code the spec correctly?

7. Architecture Documentation help programmers to interpret coding specifications with greater assurance and proximity. Without such documentation, programmers are left to interpret only general guidelines that could severely impact the speed and future releases of a software system. Remember, many applications go through many releases and so coding is revisited not necessarily by the same programmer.

8. User Documentation helps customers and vendors to bond, because user manuals can be revamped and transformed into training presentations using programs like Microsoft Power Point. Usually, trainers have a more superficial understanding of a system, while the documentation person has a very in-depth knowledge of the system.

Negative Aspects of Software Documentation

1. Writing documentation is a time-consuming process and many revisions are necessary in the writing process. So, patience is needed, and time is not always on the side of the vendor.

2. Writing quality documentation depends upon positive support from the vendor’s staff. Technical writers need the time and information generosity of managers, programmers, quality assurance, and even customer service.

3. Writing documentation requires a Technical Writer or Documentation Specialist. Depending upon the writer’s location (e.g. United States versus India), his or her salary requirements will vary greatly. A good Technical Writer in New York City might command an annual salary of $80,000 and upward. A Technical Writer from Delhi, India, for example, might only require an outsourced fee of $2000 per month as they work for you. But like the old proverb goes, “as you give so shall you receive.” Sometimes it is better to pay a healthy salary for a good writer for you to get top return and quality documentation that will serve the company for a long time into the future.

Documentation: Good or Necessary Evil? The decision is yours

Tags: Writing, programming //