Software Development Design Phase

What makes up a system design?

Having over 30 years of experience in software development, I currently serve as the Director of Development at PC Bennett Solutions. At PC Bennett, we implement streamlined business management solutions for companies that often have complex processes and system requirements.

In designing a new system, or new integrations to a current system, it can be tempting to just start building out the new code. Often people forget that the most important stage of any software development project is building a detailed design document.  PC Bennett strongly believes that a successful development project is entirely dependent upon a thorough and complete design that has been reviewed, revised, and approved by the end-users and major stake-holders of the software.

A successful design will include:

  1. A screen mockup and complete description of every major screen in the system, including a description of each field on the screen and its purpose.
  2. A complete description of every major process in the system (flow of data, calculations, posting processes, etc.) with diagrams (such as flowcharts) as appropriate.
  3. A report mockup and complete description of every report to be built for the system, detailing the source of the data to be included, filtering, sorting, and subtotaling options.
  4. A detailed description of the technology to be utilized.
  5. A complete and detailed field-by-field table specification for each new table to be built for the system.
  6. A list of existing table “objects” to be utilized or to be integrated with, along with a field-by-field list of custom fields to be added to these objects (note, a table “object” may refer to a virtual table entity from the existing application’s perspective; this entity may be comprised of one or more actual SQL tables).
  7. A data dictionary tracking all of the data fields to be used throughout the system (mapped to the tables using them).
  8. A chart of table relationships (showing key field links between them).
  9. Data Flow Diagrams as appropriate to explain how data “moves” through the software system.
  10. A description of the user-security methodology to be utilized.
  11. List of anything that will NOT be included in the system (so that there are no invalid assumptions).

This article is meant to be a more technical perspective on the Design phase of a system implementation. For a higher level understanding, check out this post.

Structure the Design Documentation

The finished detailed design will include both application/domain level information (for review by the client) as well as technical information (for use by the development team).  Often times these are divided into separate documents, but I prefer to combine them into a single document, with sections clearly delineated (so that the client does not get bogged down in trying to read and understand the technical details).  I prefer this combined-design approach for the following reasons:

  • It eliminates the concern about the two documents becoming out of sync as modifications are made (or of a key stake-holder reviewing mismatched versions of the two documents)
  • It is critical for development staff to understand the “why” (i.e. application level), not just the “how”, so they should have ready access to the client-focused design documentation as they are proceeding with the development

A Final Blueprint

A proper detailed design, as described above, can be considered an end “product” in and of itself, as it has value as a concise description of the software system to be built, much as an architectural blueprint for a building.  The design document should be such that it can be presented to any software developer (assuming the proper technology skills) for creation of the end software system.

What do think are often the greatest challenges to preparing design documentation?