Do you ensure that your programmers and project managers have an adequate technical reference library?

When you consider developing new software, or implementing additional software out-of-the-box, do you and your staff all of the software hooks, routines, and interfaces currently used? Good technical reference documents help ensure seamless application development, installation, and integration.

One of the most often forgotten elements of system documentation is the technical reference. Why? Who knows. Perhaps the pace of technological innovation has outstripped the ability of companies to keep up. Particularly with small- and medium-sized businesses, the notion of a technical reference library is almost foreign. However, this problem does not lie with small businesses; not hardly.

Real-Life Examples, or Horror Stories

Example #1: The Agile Development Group

According to the Agile Manifesto, Agile system development is founded upon these values:

• Individuals and interactions over processes and tools
• Working software over comprehensive documentation
• Customer collaboration over contract negotiation
• Responding to change over following a plan

The emphasis is on getting working software out of the door and to the customer as quickly and efficiently as possible. And, there’s absolutely nothing wrong with that principle.

The problem resulted from the Scrum process used and management’s need to reduce overhead costs. For instance, it is true that a database designer spends her or his time more efficiently when coding. Times taken to explain the code or review a diagram of the architecture were considered impediments to the sprint. Impediments lower the return on investment; they must be eliminated. Besides, the artifacts left from each Scrum sprint formed the technical reference library for the project.

Problem: No single source remained to describe the code as finally designed and implemented. This affected subsequent upgrades, especially when new programmers were brought employed.

Example #2: Marketing-Driven Rapid Development

During the latter stages of the Dot-Com Boom, further fueled by the Y2K Problem, I worked with a company that developed and deployed many inter-related applications as rapidly as possible. The company was a true online service, providing public data on individuals to a buyer.

• Each product had to be available online on a date promised by Marketing
• Marketing never consulted with Development before setting release dates
• Each product was a different search tool
• Each tool was a separate software project
• Each project used data, routines, & application programming interfaces (APIs) created for other tools
• Each new software tool “broke” an existing software tool

Problem: Although the programmers for this company were a stable group (almost no change in personnel over a period of years), they had no technical reference library to use. Given the thousands of lines of code developed over the years for each separate tool, it is not hard to understand why a new tool caused an existing tool (or three) to crash. The emphasis was always on rapid prototyping and rapid application development to meet the release deadlines set by Marketing.

The Learned Lesson

You and your company need good technical reference guides. Even if you undertake a project to replace an existing application, your developers need to review the legacy code and architecture to avoid conflicts and delays in delivering your product.

Distribution

You can publish your technical reference manuals in a series of Wiki articles on your Web site. You should also retain electronic PDF copies in a technical reference library on a hard disk drive. For greater assurance, it is a good idea to backup your reference library on a set of CD-ROM or DVD disks.