Page #141 (21.5 Expert System Workflow Tools)

21.6 Self-Documenting Approaches

Self-documenting approaches to SPI go hand in hand with automated workflow methods and expert system workflow tools. The heart of most popular SPI methods is manual documentation. That is, popular SPI methods call for documented customer requirements, specifications, project plans, code, and tests. This seems relatively innocuous on the surface, but when we look deeper, we see dozens of documents hundreds of pages thick.

Take, for example, a popular international standard for software engineering. It has five major clauses or types of software processes. However, its software development life cycle alone calls for 27 documents. Many of these documents must be produced for every major system function of a single application or software project. A good software system specification requires over two weeks of labor to perform, at a very minimum. Multiply this by 27 or more, and the economic burden becomes apparent.

Also consider the fact that most people hate the documentation task. They aren't good at it and they don't have the slightest idea how to conform to a software engineering standard. A court of law couldn't make some people conform to the requirements of a software engineering standard.

Self-documenting approaches are the antithesis of popular SPI methods which require people to produce dozens of documents. Manually intensive SPI methods seem to have as a fundamental necessity making humans do what they simply will not do. Self-documenting approaches consist of automating the creation of software documentation.

Software documentation, apart from training in a SPI method, is the single largest source of SPI costs. This holds true for popular approaches to SPI. Once again, software engineering life cycle standards call for the creation of dozens if not hundreds of software documents, and that's only for a single software project which only adds marginal value at best. Documentation requirements of SPI methods are the source of resistance from project managers, engineers , and programmers. Automating documentation production may be the linchpin of successful SPI.