Software Engineering Design Documents (part 2)

Why create Engineering Design Documents? One reason – to communicate. (Did I blow your mind man?)

When a software team forms, one of the first things they do is meet and discuss the project. It may be to review the project goals & requirements. Perhaps it is something more involved like a TSP launch. Whatever the purpose, eventually the team documents something. There are two reasons for this:

1. To communicate with yourself, someone else, or another group

2. And/or to scribe information for future reference

Documents are a natural & expected output of software teams, whether they are just starting or finishing a project. The reasons for a documents’ existence are simplistic, but it is amazing how these reasons manifest with such complexity when you append ‘engineering design’ to the document’s title.

As I mentioned in a previous post, the engineering design document outlines the manifestation of requirements in a software system. So why is this outline necessary? Let me expand the two points I provided using examples:

To communicate with yourself, someone else, or another group (within project scope)

I write notes. Whiteboards, notebooks, printed documents, OneNote’s, it does not matter. I do this because I need to collaborate with myself when I am creating a view of the software I am responsible for creating or maintaining. I cannot think through my designs between the hours of 9-5pm only. It is common that I walk in to work with a few slips of paper with simple sequence diagrams on them. These slips of paper help me form a mental picture of the code I am working with, or the code I will be developing. I find these low-fidelity notes very useful. I consider these notes to be a form of design documentation. They are not ready for formal presentations to the team, but they do capture an aspect of the design I am working through. The point I am making is that a design does not need to be a formal word document; it is what works to capture the design & make it understandable to the reviewer. In this example, the reviewer is I.

To scribe information for future reference (outside project scope)

Through the development lifecycle, a team considers many designs to find the right solution that fulfills a requirement. Eventually, the team blesses one design to move forward. The team may decide that the design needs documentation for future reference. The goals, decisions, and supporting material all may need to be included with the design. The team then scribes the design for all to view. Please note that I use the term ‘team’ loosely. It could a single individual, a subgroup of the team, or the entire team. Once the design is scribed, it is reviewed & signed-off. Now anyone who wishes to understand the design can review the document at any point for him or herself.

Design documents serve two useful purposes. The examples above outline needs both within & outside the scope of the project. However, the examples only provide insights in to why you would document a design. These whys are straightforward to anyone who has designed software systems. However, the controversy with engineering design documents is not ‘why’ you would document, but ‘when’ and ‘what’.

I plan to cover ‘what’ to document in ‘part 3’. This post is about ‘when’.

I mentioned before that engineering design documents serve two key roles. So when should you document your design to serve these roles? In my opinion, the documentation for a design needs to be available just before the team needs the design.

When a team is working towards a specific goal, you are working along a schedule. The schedule is divided in to what will be done & for when (milestones). Each team member does his/her part working towards these milestones. As they are met, code is checked in, tested, and written off as complete.

However, nothing goes as planned. Perhaps some milestones finished earlier than others. Maybe some have leapfrogged because of feature scoping. Sometimes the team confronts a technical limitation or issue. Whatever the cause, the team needs to adjust its strategy to absorb these changes in to the plan.

Part of adjusting is reprioritizing. This is the process of evaluating outstanding tasks & determining their priority ordering. When a project is not proceeding as planned, how often is it that the task to document becomes the top priority? I doubt it ever does. Why? Documentation is strictly a communication tool and does not replace communication. When things change, teams meet, discussions ensue, & a new ‘plan’ is devised. The team then moves forward with the revised plan. I have never seen a team create or update an engineering design document to communicate a change or the need for a change. The team finds it more useful to ignore formal documentation & deal with the issues at hand. Source code & whiteboards usually become the documentation medium of choice to describe the problem & solution. This style of documentation is the most expedient method to communicate & coordinate. Solving mission critical issues is always the priority, not engineering design documentation. This means that engineering design documents are not critical to pushing a project forward.

Here is my take on pre/post-release design documentation.

The frequency and scope of changes will reduce over the course of the project. In the early stages of development, forget about a formal engineering design & document for yourself when required. This allows you to focus your time on project-critical tasks. If someone requires information from you, sit down & discuss it with them. If they need documentation, provide them with the bare minimum of what they need. It should have just enough information to get the point across & no more. If someone requires the documentation at a certain time, draft it as late as possible but before it is needed. Remember, documentation should only serve to supplement your communications (e.g. UML diagrams), not replace them. If you only document what is needed just before it is needed, you will focus your documentation to compliment project-critical tasks, and not spend time on content that neither you nor anyone else cares about.

Once the project has completed, you can switch to documenting the software system in detail, when the risk of change, and hence rework, will not be a pressing concern.

Whew! This post turned out to be more verbose then I planned, but it will give you a better perspective on my philosophy of documenting engineering designs.

Some of you may have recognized that some of my opinions mirror agile methodologies. If you want to learn more about agile documentation, AgileModeling.com is a good starting point.

————–

The next time you find yourself facing a design documentation task, as yourself the following:

Q1: Is the design subject to change? If yes, are you risking documentation rework?

Q2: If something changed in your design, is it likely that you will update your document before the release of the product?

Q3: Would spending some time expressing your design with those who require it be faster than writing the documentation itself?

Q4: Am I doing the minimal amount of work to convey my message?

Q5: Can I commit effort to document the design after the release of the product?