Reply to comment

Big IT development projects invariably run into trouble with their documentation. The problems range from disordered libraries of incomprehensible, incomplete documents through to simply having no documentation at all.

This article takes a look at the common problems that arise in the documentation area and suggests some simple fixes.

 

[toc list: ul; title: Contents; minlevel: 2; maxlevel: 3; attachments: 0;]

 

The table below summarizes some of the major causes of documentation problems, and gives you links to my preferred solutions.

Problems	Causes	Solutions
Badly-written, difficult-to-understand documents	Developers writing documents	Use real writers
	Methods too complex/demanding	Minimal use of methods
	Insufficient resources	A proper budget
	Too many acronyms	No new acronyms
	Insufficient feedback	Continuous review/testing
	Fragmentation of information	One document per reader
	Bad grammar/style	Professional editing
Unattractive documents that do not sell the product	Designers writing documents	Use a graphic artist
Documents that are out of date, incomplete, or not yet started	Insufficient writing resources	A proper budget
	Poor planning	A proper plan
	Overloaded designers	Use real writers
	No transfer of responsibility	Living documents
Too much time spent on documentation, causing project costs to balloon.	Methods too complex/demanding	Minimal use of methods
	Too much time spent in review	Continuous review/testing
	Fragmentation hinders reusability	One document per reader
	Poor planning	A proper plan
Too hard to find required information	Too many documents	One document per reader
	Insufficient indexing	A proper library structure
	Poor storage/retireval methods	Use web pages
	No contents lists	Require contents lists in all docs
Those who need to know being kept in the dark	Failure to distribute information	Use web pages

Our solutions come mainly from my extensive experience (25 years in the industry!) and my understanding of what will work in a project and what will not.For each solution we have asked ourselves three questions, better for us to understand the impact the solution might have on the project. The questions were:

• Is it simple?
• Does it cut costs?
• Will it improve quality?

In most cases, the answers to our questions were yes, yes, yes!

 

Technical Writing 101: A Real-World Guide to Planning and Writing Technical Documentation, Second Edition

The Elements of Technical Writing

Managing Your Documentation Projects

 

Use real writers

Even in large projects, it is common that the engineers, designers, and programmers write the document, even though they have little or no experience of writing high-quality documentation, and few of them have received any training in the subject. Most project members find documentation hard and would prefer not to do it at all!

Some companies have a set of "documentation process methods" that require that the developers are supported by a team of documentation experts --  methods specialists, technical writers, SGML/XML/HTML experts, editors, subject-matter experts, reviewers, coordinators and so on -- yet, invariably, the project budget turns out to be too tight to employ all these experts, and nor is it easy to find individuals who can fill these roles effectively. The result is that the designers never get the support they require, and are just left to get on with the job the best they can.

Using inexperienced, unskilled, untrained, unsupported people to perform a highly-specialized task such as writing documents slows down development, adds to costs, and reduces document quality. Most of what gets written could be just chucked straight in the wastebasket.

 

Clearly, the most sensible solution is to employ skilled, trained, experienced technical writers in place of designers. (After all, you wouldn’t pay a technical writer to write code, so why would you pay a developer to write documents?)

And that means the project must find or create and keep specialists whose job description is “Technical Writer”.  This is not easy to do. Both planning and commitment are required if it is to happen.

The simplest approach is to establish a writing team composed of both consultants and employees and have them work together for, say, a period of six months. Once the documentation system is running smoothly, the employees (who have received six months on-the-job training) will take over the project and the consultants contracts will be terminated.

It takes time to find suitable employees and recruit technical writing consultants, so recruitment must start early - long before the writers are required. We estimate that recruitment should begin no later than two months before the actual employment date, i.e. for an employment date of 1 September, recruitment should start no later than 1 July.

Make sure that all writers on the project are required to pass an English language skills test (you would be surprised how many technical writers there are who cannot write!). If you hire someone, make sure they can show a portfolio of documents that they have written for other customers. And always check references!

 

Minimal use of methods

Most large companies have a set of "process methods" that describe which documents need to be written, how they are to be reviewed, where they should be published, and so on.

In my experience these process methods always share one feature in common: they are too complex!

One process method I encountered, for example, consisted of over 950 templates, instructions, and examples for writers. That's right, 950 other documents to read before you could get started! To write a simple functional specification of part of a product being built a writer had to read and understand a pile of documentation 8 cms high! In another company the instructions for writers was by far the longest document in the entire company!

To state it plainly, many projects are drowning in "processes" and "methods" documentation and, what's more, if you don't keep an eye on them the technical writers will create even more of the stuff.

Any method that requires more than a few pages of explanation is already too complicated.

Managing Projects Large and Small: The Fundamental Skills to Deliver on budget and on Time

The Practical Guide to Project Management Documentation

The Handbook of Technical Writing, Eighth Edition (Handbook of Technical Writing Practices)

I propose a much simpler solution: no compulsory methods. For internal documents (documents never seen by the customer), the writers should be able to use any method they likes, provided it conveys the information clearly and completely, and is kept up-to-date. For customer-facing external documents (user manuals, etc.) write only one document of each type and stick to a standard template.

In both cases, use continuous testing and review will help ensure clarity and completeness.

So I say this: don’t waste time creating process methods if a perfectly satisfactory document can be written without them. The goal must not be that the document satisfies method, but that it satisfies the reader!

 

A proper budget

The true costs of documentation to a project are not easy to assess. If the cost of documentation is calculated as simply the cost of writing it, the total cost will appear to be only a small portion of the total project budget. But the true cost of documentation is a sum of the writing cost and many, many other hidden costs, like:

• The cost of reading the documents. How many hours did you spend in review meetings?
• The cost of applying the information (including the rework necessary because the information was incomplete or wrong).
• The cost of administering the document library and keeping track of the documention
• The cost of testing the procedures in the documents, finding errors, sending bug reports, and making change requests.
• The cost of sorting out all design problems caused by faulty documentation.
• The loss of potential sales to customers who didn’t like what they read.
• The cost of recruiting and managing the writers.

Seen this way, the cost of documentation to a project is huge!

The average project member spends most of a project dealing with documentation in one way or another. Even decisions which have apparently little to do with documentation (such as which chip to use, or what attributes to assign to a C++ object) are ultimately documentation work, because the decisions must be recorded and conveyed to everyone who needs to know about them, usually through some form of document.

 

A simple documentation project requires that a proper budget be established for the documentation. The budget for documentation should be separate from the budget for non-writing activities: designing, programming, testing, project management, training, and so on.

The budget must be established at the start of the development project and be based on:

• A documentation policy statement (a document, required by ISO 9000, which clearly states the ambition level for documentation within the project).
• The documentation plan (initially a list of the documents that are considered essential to the project's success).
• The project requirements.

The budget must be authorised by the project manager (who for this reason is the sponsor of the project). The responsibility for allocating the budget, once authorized, should rest with the leader of the writing team.

I believe it is critical to the success of the documentation side of the project relies on having a proper budget that covers the time an resources needed for every aspect of documentation. When the costs of documentation are mixed up with the costs of designing, programming, testing and management it is very hard to prioritize documentation.

Designers, testers and even project managers should have account codes for documentation that are different from their account codes for real design, testing and management. Controlling how resources are allocated to the documentation work gives a clearer picture of the true cost of documentation for future projects.

 

A proper plan

The budget for the documentation project must be based on the project plan. The plan (written and maintained by the documentation team leader) must list every external document type, assign responsibilities, and show the estimated effor for each. It must also be clear an simple. The project begins with a one month familiarisation phase, during which time all members of the project team receive training in the coming product and the requirements on it.

After this comes the main writing phase when drafts of all the external documents are written. For big projects, this phase will last months. At all times during this phase, the documents in progress must be available for inspection at all times.

When it has finished, the external documents become requirements on the product.

After the main part of the external documentation project has finished, a maintenance project takes over, staffed by permanent employees. (By this time the permanent employees will have effectively received several months on-the-job-training from the contractors).

It is essential that the writers receive a proper grounding in product and in the hardware and software in which it is being implemented. As it is impractical to have more than one training course, all writers should start on the documentation project on the same day. This implies that recruitment must be start several months before the project start date.

So as not to waste time and money, everything must be prepared for the project start date (ID cards, logins, e-mail addresses, contracts, terminals, software, etc).

 

No new acronyms

Discourage the use of acronyms: they make documents too hard to understand. Acronyms and abbreviations are a form of encoding: a cryptographic system if you like. By using as few acronyms and abbriviations as possible we can dramatically improve make all our documents simpler to read.

However, I recognize that certain acronyms are understood by customers who are familiar with international standards. Therefore, the simple strategy requires that any acronyms of abbreviations used in a project documents is accompanied by a reference to an international standard in which the term is clearly defined and explained.

 

One document per reader

The greatest failing of the standard documentation methods is their complexity: they require too many documents to be written. A large project could write perhaps 1000 documents before it ends. The simple strategy attempts to dramatically reduce the number of documents that need to be written by the project.

A goal is that every person writes one document, and one document only. That is, if there are 50 people working on the project, 50 documents will be written. That’s about all one person can cope with in a hectic working environment.

The Operator’s Guide, the System Administrator’s Guide and the Product Specification should be written by two different experience technical writers.

In an ideal world we would like this strategy to be applied to the designers and managers of the project. That is, the Project Plan will be written by the Project Manager. The Overall-System-Responsible will write the Product Functional Specification. And every designer will write just one Notebook that contains all the information that he or she needs to convey to other project members and to members of future projects. The Notebooks can be free-form (that is can be written anyway the designer likes) as long as it succeeds in being clear and complete and communicates what needs to be communicated. In many cases the Notebook can be made into a simple web site, which can be accessed by co-workers around the world.

For example, all aspects of the management of the documentation project - the project plan, the resources, known problems, current document statuses, locations, responsibilities - will be described in the Documentation Team Leader’s Notebook. The intention here is to make it easy for other project members to find the information they need without referring to several different documents. Thus if a project member has a ques­tion about documentation they can refer directly to the Team Leader’s Notebook where they will find that information - and other information that is of interest to them.

 

 

Living documents

When development of different product components is running in parallel, documentation must also be done in parallel. This is necessary if the product is to be brought to market in good time. Unfortunately many company documentation methods are too complicated and incomplete to allow this to happen.

The simple strategy requires that all project documents are written in parallel.

This is only possible because because the library structure is greatly simplified and all documents have a clearly defined role to play in the project.

All documents are living documents. That is to say:

• A document is always correct and up to date at all times (problems with documents must be corrected by the author immediately
• A document exists for the entire life of a project
• Someone, somewhere is always responsible for the document
• The document is ready for review or testing on demand
• The latest version of a document is always accessible on line
• The latest version of a document and all its previous revisions are always available.

I cannot think of any critical project document that does not need to follow these rules. A requirements specification, for example, must be continually updated as requirements are clarified and new requirements added as the project pro-ceeds. A manufacturing instruction needs to be written as the product is being devel­oped and crucial decision that will affect the later manufacturing process are being made. The Operator’s Guide can act as a requirements document early in the project, give valuable feedback as the user-interface is fine tuned, and be used as sales literature at any time.

 

Continuous review and testing

Far too much time is spent doing formal reviews of documents. Typically, a team of three to five people will read the document and then hold a review meeting with the document author. This meeting can last several hours. The review team may make only minor comments (which better could have been conveyed by e­mail), or may reject the document totally (which is probably of little help to the writer). Such a review can easily cost the project half a working week in effort that could have been better spent elsewhere.

Every document on a project will usually have one review; some will have several. If a project writes only 500 documents and does a thorough review of each one that’s 10,000 working hours - and, at present, no reasonably large project write that few docu­ments anyway.

 

Clearly, a different approach is needed. Having living documents is the key here, because it allows all documents to be out on on review with other members of the project team at all times. As every document must always be up to date, any errors that are found in the documents must be corrected immediately (or at least before the next build).

Anyone who spots and error in a document, or finds the document confusing, or incom­plete is deputized to sort out that problem. The person finding the problem must inform the author and follow up to make sure that a correction has been made.

Continuous peer review can save many thousands of hours of work, but it must be clearly established as a project policy and therefore requires some effort to be invested.

The leader of the documentation project is responsible for making sure that peer review works.

In any case, we believe thattesting is a much stronger strategy for ensuring the quality of the project documents than review. Because all documents are living documents they are available for testing at all times.

Testing will, of course, be carried out by the Integration and Testing group. However, the writers of critical product documentation must have available to them a test rig so that they can continually perform their own testing. It is impossible to write sensibly for an operator if the user-interface has not been fully defined and at least partly implemented.

 

Professional editing and graphic design

Editors and graphic artists have an important role to play in ensuring the quality of documentation. All external documentation must have an editorial check by a competent editor who is familiar with the product. The editor must take part in the familiarization course (first month) and in the final polishing phase.

A graphic artist performs a similar service to an editor, except that he works with the graphic elements of the documents (and also the user interface). In addition to prettying up the documents (and thus helping to make the product more sellable), a principal role of a graphic artist is to ensure consistency across all external documents. Ideally, the graphic artist should be present through the main documnet creation phase.

 

A proper library structure

The library structure must be simple enough for a reader to understand at a glance where they should look to find the information they require. This is clearly impossible with the standard methods which require that hundreds of different documents are written for the project. Instead, we propose a much simpler library structure which is takes account of the readers of the documentation.

 

Large documentation projects invariably run into trouble, and I hope that some of the advice given in this article will help you save your project from blowing out the cost because of documentation issues.

 

*     *     *

 

At Straightforward AB we offer a range of documentation services to help you keep your project on track, including technical writing and documentation project management. Our clients include major companies in Sweden and Australia. Our head office is in Stockholm. If you need help with your documentation, drop us a line.