Pragmatic Artifacts

Conventional document-driven approaches squandered incredible amounts of engineering time on developing, polishing, formatting, reviewing, updating, and distributing documents. Why? There are several reasons that documents became so important to the process. First, there were no rigorous engineering methods or languages for requirements specification or design. Consequently, paper documents with ad hoc text and graphical representations were the default format. Second, conventional languages of implementation and deployment were extremely cryptic and highly unstructured. To present the details of software structure and behavior to other interested reviewers (testers, maintainers, managers), a more human-readable format was needed. Probably most important, software progress needed to be "credibly" assessed. Documents represented a tangible but misleading mechanism for demonstrating progress.

In some domains, document-driven approaches have degenerated over the past 30 years into major obstacles to process improvement. The quality of the documents became more important than the quality of the engineering information they represented. And evaluating quality through human review of abstract descriptions is a highly subjective process. Much effort was expended assessing single-dimensional surface issues, with very little attention devoted to the multidimensional issues that drive architecture qualities, such as performance and adaptability.

Document production cycles, review cycles, and update cycles also injected very visible and formal snapshots of progress into the schedule, thereby introducing more schedule dependencies and synchronization points. For example, the following scenario was not uncommon on large defense projects: Spend a month preparing a design document, deliver the document to the customer for review, wait a month to receive comments back, then spend a month responding to comments and incorporating changes. With many, many multiple-month document review cycles to be managed, scheduled, and synchronized, it is not surprising that many such projects ended up with five-year development life cycles. Lengthy and highly detailed documents, which were generally perceived to demonstrate more progress, resulted in premature engineering details and increased scrap and rework later in the life cycle.

A more effective approach is to redirect this documentation effort to improving the rigor and understandability of the information source and allowing on-line review of the native information source by using smart browsing and navigation tools. Such an approach can eliminate a huge, unproductive source of scrap and rework in the process and allow for continuous review by everyone who is directly concerned with the evolving on-line artifacts.

This philosophy raises the following cultural issues:

• People want to review information but don't understand the language of the artifact. Many interested reviewers of a particular artifact will resist having to learn the engineering language in which the artifact is written. It is not uncommon to find people (such as veteran software managers, veteran quality assurance specialists, or an auditing authority from a regulatory agency) who react as follows: "I'm not going to learn UML, but I want to review the design of this software, so give me a separate description such as some flowcharts and text that I can understand." Would we respond to a similar request by someone reviewing the engineering blueprints of a building? No. We would require that the reviewer be knowledgeable in the engineering notation. We should stop patronizing audiences who resist treating software as an engineering discipline. These interested parties typically add cost and time to the process without adding value.

• People want to review the information but don't have access to the tools. It is not very common for the development organization to be fully tooled; it is extremely rare that the other stakeholders have any capability to review the engineering artifacts on-line. Consequently, organizations are forced to exchange paper documents. Standardized formats (such as UML, spreadsheets, Visual Basic, C++, and Ada 95), visualization tools, and the Web are rapidly making it economically feasible for all stakeholders to exchange information electronically. The approach to artifacts is one area in which the optimal software development process can be polluted if the philosophy of the process is not accepted by the other stakeholders.

• Human-readable engineering artifacts should use rigorous notations that are complete, consistent, and used in a self-documenting manner. Properly spelled English words should be used for all identifiers and descriptions. Acronyms and abbreviations should be used only where they are well-accepted jargon in the context of the component's usage. No matter what languages or tools are used, there is no reason to abbreviate and encrypt modeling or programming language source identifiers. Saving keystrokes through abbreviation may simplify the artifact author's job, but it introduces errors throughout the rest of the life cycle. Disallowing this practice will pay off in both productivity and quality. Software is written only once, but it is read many times. Therefore, readability should be emphasized and the use of proper English words should be required in all engineering artifacts. This practice enables understandable representations, browseable formats (paperless review), more-rigorous notations, and reduced error rates.

• Useful documentation is self-defining: It is documentation that gets used. Above all, building self-documenting engineering artifacts gives the development organization the "right" to work solely in the engineering notations and avoid separate documents to describe all the details of a model, component, or test procedure. If you find that information, and particularly a document, is getting produced but not used, eliminate it in favor of whatever is getting used to accomplish the intended purpose. Strive to improve its self-documenting nature.

• Paper is tangible; electronic artifacts are too easy to change. One reason some stakeholders prefer paper documents is that once they are delivered, they are tangible, static, and persistent. On-line and Web-based artifacts can be changed easily and are viewed with more skepticism because of their inherent volatility. Although electronic artifacts will and should be met with healthy skepticism by many stakeholders, it is simply a matter of time before the whole world operates this way. The advantages are substantial and far-reaching across many domains. Rest assured that tools and environments will evolve to support change management, audit trails, electronic signatures, and other advances in groupware so that electronic interchange replaces paper.

It is extremely important that the information inherent in the artifact be emphasized, not the paper on which it is written. Short documents are usually more useful than long ones. Software is the primary product; documentation is merely support material.

Project Management Made Easy

Project Management Made Easy

What you need to know about… Project Management Made Easy! Project management consists of more than just a large building project and can encompass small projects as well. No matter what the size of your project, you need to have some sort of project management. How you manage your project has everything to do with its outcome.

Get My Free Ebook

Post a comment