Natural Order Development

Software quality encompasses a number of factors such as number of defects, complexity, functional behavior coverage, and usability. The higher the quality of a solution the lower the total cost of ownership (TCO) as well as the higher the return on investment. As obvious as this idea is many developers fail to consider any of it while producing a solution. In the fast past world of software engineering most people involved get caught up in the idea that motion equals progress. Worse is that it is often considered better to get a function coded than to spend time considering and documenting the design.

Software should be engineered with the philosophy that it is better to be effective than efficient. By effective I mean that the quality of a solution should match the expected functional needs. For a quick through away program to be run once to correct some issue the quality level is only needed to be enough to accomplish the basic task. However, any solution which will be shared should have a high level of quality.

As already said software quality encompasses more than simply efficiency of the code. In fact quality can be measured in the ratio of return on investment (ROI) vs. total cost of ownership (TCO). Therefore, anything that affects TCO has a dramatic affect on quality. One of the most neglected areas of quality is documentation. Documentation affects the maintenance costs, the learning curve, and the usability of a solution. A solution's documentation is measured by a number of factors such as how up to date is it, how relevant for the target audience is it, and how complete is it.

To this end it is important to provide automation and quality checks on project documentation. The documentation process should be easy to work with and yet keep the documentation from being out-of-date, inaccurate, or irrelevant. Normally poor documentation quality is a byproduct of the lack of automation between work done on a project and the publication of the documentation changes needed. This can be easily seen in the traditional desktop publishing applications usage and coding styles used where to change documentation developers must spend significant time word-smithing instead of code crawling. For most software engineers the process of writing documentation is both a laborious and boring processes only done when absolutely required.

If there was a means to improve the documentation process through automation and process the gains are tremendous. Replacing documentation applications with an automated publishing solution improves project quality, as well as reducing the cost of production (aka investment).

A key to improving the documentation process is to apply the principles of modern production: eliminate waste and apply automation wherever possible. For publishing technical documentation, this translates into giving developers the ability to create information in small, reusable components that can be automatically assembled for different purposes – both for different types of documents, as well as for different audiences (e.g. end users, administrators, developers, etc.). This process requires dynamic publishing solution that is capable of automatically publishing to multiple types of media, including print, Web and other forms. The benefits of developing such solutions are:

• Standardized documentation procedures
• Increased frequency publication and improved timeliness / accuracy of the documentation
• Improved project quality
• Reduced time-to-market for new or revised products
• Reduced translation costs
• Reduced maintenance costs through understanding of the products when fixing features

There are a number of technologies and processes that can be applied to improving the documentation process. Specifically:

• Using Behavior Driven Design to document the functional specifications in an executable business domain language
• Using a short iteration project management style that improves the feedback loop between the clients and the developers
• Using an automated framework for the code languages which produces clean API documentation that is tied into the continuous integration and build processes
• Writing user guide sections before implementation begins
• Having an enforced done criteria that includes review of the documentation vs. the functioning deliverable