white papers business analyst and technical writer

 Home  Who We Help  Services  Approach  Case Studies  Resources  Contacts  About Us


Most of our communication is in writing. We write plans, requirements, specifications, reports, tests, etc. For a major IT project, the volume of paper can be enormous, but is it valuable?

In today's fast-paced, high-stress, businesses, no one has the time to read volumes of information no matter how nicely formatted and presented. Yet, many companies continue to turn out the equivalent of a multi-volume encyclopedia on project after project.

Why do we continue this archaic practice?

Information is captured in writing to create a record of events, ideas, problems and solutions. Though in many cases, documents serve a more important purpose - they make people think. Authors must think through problems thoroughly to adequately convey information. Readers are challenged to grasp information and add comments of their own.

It's the thinking process that is really important, not the document.

Unfortunately, documentation often serves as a vehicle for showing off what a good job we're doing rather than simply conveying information. Elaborate and fancy documents require a lot of effort but rarely provide equivalent value.

Let's take a business requirements document as an example of this phenomenon. Someone decides that there should be a common corporate format for requirements documents. A template is created and distributed. Templates typically contain formatting guides such as fonts, layout, etc. as well as section headings covering all the major topic areas.

Of course, in order to make the template universal, it must contain everything that anyone may ever discuss in a requirements document. It's not unusual to find document templates that are 20 or 30 pages long.

The author of the requirements document takes the template and starts filling in sections, including those that do not apply. Once complete, the requirements document is visually appealing and quite long yet may only contain a few pages of valuable content.

Such lengthy documents tend to discourage readers. They are too lengthy to absorb electronically and too bulky to print out and thumb through. Readers tend to go for the executive summary, which while conveying a few major points is short on specifics.

Most of the time invested in writing the requirements document is wasted as few people bother to read it and those that do are distracted by all the irrelevant sections. The critical success factors get lost in the weeds.

There is a better way. Apply the principles of agile development and lean programming to produce documents your teams can really use.

1. Focus on content not form.

Before writing any document, there a few questions you need to answer. What is the purpose of the document? Who is the intended audience? How long will the information be needed?

If the document's purpose is to impress someone such as a customer or business partner, appearance is important and the extra effort is justified. If the document is strictly for internal team use, appearance shouldn't matter.

If the audience is executive management, a more formal approach is justified. If the audience is the core development team, keep it informal.

Documents that have longevity should be more formal and thorough than those that only serve a short-term communication need.

Going back to our requirements document, if the resulting software is being sent to customers and will have a long shelf life, formality can be helpful. However, if the software is strictly for internal use and has a limited audience, formality is wasted.

Reverse your thinking and follow an iterative approach. Rather than beginning with a lengthy formal template and looking for ways to simplify it, begin with a short informal approach. Increase length and formality as needed. To save time, send out an informal document to get everyone moving and add formality later.

2. Keep it brief.

We like to create lengthy documents that cover all aspects of the problem and corresponding solution. Yet, in most companies, people are specialized. Most of the document contents don't apply to particular individuals who ask themselves if it's worth the time to wade through a tome to extract the few points of interest to them.

Break up long rambling documents into a few short ones where each is tightly focused. Your goal is collaboration not just communication. Big documents communicate but they do little to enhance thought-provoking discussion.

Don't use a document template to define and control content. The template should define appearance and overall structure. Use a checklist to define content and have authors only include those items that are appropriate to their projects.

3. Minimize the work effort.

Seek out ways to minimize the work to be done. Many problems are solved on a whiteboard. Often, someone takes the time to type up what's on the whiteboard, re-draw the diagram, and send an email to the team. Yet often, the information is needed but the formality is not. Why not just take picture or two of the whiteboard using a cell phone camera and email it?

Avoid duplicating information. Rather than copy content from one document to another, simply refer to the original. Not only does this keep the new document shorter, it makes maintaining and updating document sets easier.

Recognize that the most efficient way to convey information is face to face. Documentation should encourage and facilitate discussion. Too often, it has the opposite effect. Agile documentation keeps teams focused on meaningful results not fancy layouts.

Vin D'Amico is Founder and President of DAMICON, your ADJUNCT CIO™. He helps companies avoid the subtle mistakes that cause missed deadlines, lost opportunities and fragile results. He shows them agile approaches that slash risk and cut development time so they get to market 25-50% faster. He helps them carry that momentum into the sales cycle using white papers and case studies that accelerate the selling process.

This article appeared in Vin's monthly Virtual Business column for the IndUS Business Journal in March 2007.

To learn more about how DAMICON can help your business, please take a look at our service programs.

Virtual Business

Virtual Business

This column appears monthly in the IndUS Business Journal.