So you think you are a good writer?

Let’s test that theory.

Word and Outlook 2007 have a feature that helps improve the readability of your document.  This tool goes beyond spell checking. A metric that indicates how easily someone can read what you write.

Try this exercise.

1. Open Outlook 2007.
2. Search help for "Test your document’s readability".
3. Open the subject and follow the instructions to enable your readability statistics.
4. Before you send your next email, run Outlook’s spell checker.
5. In the ‘Readability Statistics” window, read the values under the section titled ‘Readability’.

If the “Flesch Reading Ease” score is greater than 60, then the recipients are likely to understand it with little difficulty. If your score is less than 60, you might consider revising your email.

It is not as easy as it sounds. This blog post scored 54.9.

Click here for more information on the “Flesch Reading Ease” score.

Comment Lint

How can you clutter code with comments?  Easy, add some history.

I have had the pleasure of cleaning up some more code today.  At times this task is very boring & tedious, but I know that it is necessary to improve the quality of the product.  While cleaning up I would read whatever documentation resided in the code to better understand what was going on.  While some documentation added insight & value, other documentation did not.

Take this simple method history comment:

/**  NameOfTheMethod
*
*    purpose of the method, inputs/outputs, & assumptions
*
*    date        name      description
*    ----        ----      -----------
*    21/07/07    MPower    Initial Version
*    22/07/07    SShep     Changed parameter to const
*    23/07/07    PSherman  Removed old handler 
**/

There are three entries in this history: when the method was created, and two modifications.  So I have to ask, is this type of information valuable?

Let me put it this way, how often do you have to determine when a method was created?  How often do you require to know when it was modified?  I can count a handful of times in the past few months that I needed to determine who made a modification & when it was made.  Each time I reviewed the check-in history of the file via our source repository, because I did not believe the history that was presented to me by the comments in the source code.  In some cases the only comment was the one outlining the methods initial creation, but reviewing the code lead me to believe that other modifications had taken place since then.  My distrust was well founded because the source repository listed many more modifications which were not revealed in the comments.

Comments are all about expressing useful information which exists outside of what the code itself expresses.  While comments that list the history of a software component attempt to do this, I do not find them successful.  I get a far better understanding of any changes made by comparing two revisions of a file using Araxis Merge.  In my humble opinion, comments listing historical changes are a visual eyesore & are not worth the effort.

One of the fundamental principles in software development today is the "Don’t Repeat Yourself (DRY)" principle.  DRY plainly states that you should strive to avoid duplication.  Our source repository will always provide me with accurate & up to date information, which is much more then these types of comments can promise me.  Given that the history of the code resides in two places, I continue to rely on the source repository for my information.

————–

Here is quick stab at another practice using comments:

/*---------------------------------------------------------------------------
 * FILE: ViewController.cpp // <- do we really need to state the name of the file we are already viewing?

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?

Software Engineering Design Documents (part 1)

We had an involved & energetic discussion today about the purpose & use of engineering design documents. I am sure this discussion occurs within any organization when a document falls under the shadow of questions about its validity & usefulness. Chances are you have probably been a part of those discussions.

For those of you who do not know what a Engineering Design Document is, it describes the engineering plan to implement a requirement or a set of requirements. An alternate view is that it is the first architectural representation of the requirements, and how that architecture will manifest itself within a software system.

Traditionally we write the engineering design documentation before coding begins. Developing the documentation in this manner provides some advantages. One benefit is that team members have the opportunity to review the design, point out any defects, and offer potential solutions. The cost of correcting a defect this early in the development cycle is very small next to the monetary & emotional cost of fixing it later.

Additionally, designing thru documentation helps the engineer think through the requirements. Whenever an author is presenting the documentation to a group of people, the author must be verbose to ensure his/her writings are properly understood. This way the engineer is very explicit about why certain modifications are necessary and others are not, to fulfill the requirements.

One other minor advantage is to act as what I call a ‘broadcast’. Customers can review the documentation to verify that what will be implemented satisfies their requirements.

There are downsides too.

For one, engineers hate writing documents. They did not get in to the business of witting papers. It was the code that attracted them. The opportunity to create something and make your computer dance was too attractive to ignore. Therefore, it is a chore for many engineers to sit at their desk & write about what they are going to do, rather than doing it.

While writing a document up front is a good technique to ensure a clean & useful design, the document is by no means the final design. New insights & learning’s can sway a design at any time, even after the document has been completed and signed-off by the team. Early in the development cycle, this is very likely to occur since other team members are also designing their portions of the software system. Any discoveries on their part can affect the work that you were planning (or have planned), and hence it’s design. On-going usability also breeds new insights that, in turn, also affect the design of a software system if modifications to the original design are needed.

The trick is to balance what & when to document. Too early & you risk rework. Too late & you focus your energies away from other late stage development activities. Document everything & you end up wasting effort on design elements that are subject to change.

Thus far, I have focused on the engineering design document as a construction tool, but it also serves as a repository of information post release. Engineers who are unfamiliar with the software system can read the document to gain knowledge about its architecture & operations. This point assumes that the documentation is kept up-to-date & is accurate, which may not be the case.

Engineering Design Documents are, in my opinion, a critical step to the manifestation of requirements within a software system. However, I have differing views on when design documentation should be created, what it should document, & how much. I say differing because I compare my personal opinions with the traditional sequential approach (i.e. Waterfall) which states the design of a system must be relatively complete before coding begins. Many of the companies I have worked for followed the Waterfall model, & I have found that creating these documents within that development structure wanting.

Since there is a lot of material to cover, I will break up my opinions & insights on the creation and management of engineering design documents in to a series of future posts:

Part 2: Why create Engineering Design Documents?

Part 3: Compulsory & Discretionary Content

Part 4: Future Proofing

Part 5: Document Maintenance

See you there.