As I indicated in a post, I wanted to put up a simple, lean waterfall development process that I created and used successfully.
The process:
-
The process begins when a manager assigns a project to a developer.
-
The developer meets with the Business Analyst to review requirements. Where I was, requirements came pre-written. This is sub-ideal, since I found that working with the Business Analyst improved requirement quality, but c’est la vie. Any questions or concerns with requirements were returned to the Business Analyst for clarification/correction. If the developer is not satisfied, s/he may escalate to the manager for assistance.
-
The developer is given a maximum of 1 week to complete the analysis OR to complete sufficient analysis to provide an estimate. See templates below. The analysis is a discussion of the requirements, the challenges presented by the requirements and proposed solutions (note solutions is plural) to the problem. If the developer needs additional time after 1 week, s/he submits an estimate back to the manager with an estimate to complete analysis, design, code and testing. If the analysis is completed in this time-frame, that information would be included in the template.
-
The developer submits his/her analysis to the team for review.
-
A peer developer from the team claims the review and reviews it. No other team member will look at it. The peer should be of the same level or higher than the author of the document. The reviewer fills out a comments sheet and either approves, approves with changes or denies approval and returns the results back to the author.
-
If necessary, the author reads and responds to the comments from the review by updating the analysis document. The document goes back to the same peer for re-review. This was an important facet of the process – it was not acceptable to bypass negative comments by getting someone else to review your work. If after several passes of being unable to come to agreement, the developer and reviewer could bring the issue(s) to the manager for arbitration. I should note that by default the author of the document was considered correct, so if two solutions were equally good then it was the author’s that would win. It was not the job of the reviewer to make people do things their way, it was to assure that the author’s way would work and be maintainable. This was true for all analysis, design and coding.
-
Once approved, the developer creates the design document based upon the preferred proposed solution from the analysis.
-
Like the analysis document, the developer sends out the design for review to the team and it is reviewed by one member of the team. In the same fashion, the design is reviewed and approved or denied. All the same rules that applied to the analysis apply to the design review process.
-
Once the design is approved, the developer may begin coding. Coding is done by the developer on his/her system and checked into source control as s/he works.
-
Once coding and unit testing is complete, the developer submits his/her work for code review. Like all the other reviews, this review is done by a peer who reviews the work and responds with comments to the developer.
-
Once code review is complete, the code is submitted for testing.
-
Testing is completed by a peer developer who did not work on the coding effort. Typically, most items waited in the test phase until we were approximately 2 weeks from the release to QA date. Then the team would gather the test cases from all the design documents and execute them all in the laboratory environment.
Dealing with defects: Defects are handled just like new development work. The exact same process is followed, except the analysis is based upon the content of the defect report rather than a requirements document. Analysis was especially important here since it was previously commonplace for people to create “workarounds” in the code to avoid the situation rather than understanding what was really wrong. In limited, manager approved, situations the developer could add code to improve debugging without resolving the issue if we were unable to recreate it. It is unacceptable to return a bug as “unable to reproduce.”
The Documents:
Since I lack the formatting capability to put together a beautiful document, I’ll just provide the basics of each. My preference was to do these documents in a plain text editor anyway since it allowed diff’ing of the documents. I gave into my employees preferences to use Word.
The Analysis Document
Header:
-
Change ID# – a uniform identifier across all documents to enable tracking
-
Change Name – uniform across all documents to enable tracking
-
Target Release #
-
Analysis Hours – # of hours spent completing this document
-
Estimated Design Hours
-
Estimated Code Hours
-
Estimated Test Hours
-
Total Estimate – a sum of the three estimates above, just to make my life easy
Body:
-
Overview – a brief description of the change being requested or defect being reported
-
Modules examined – a list of code modules examined during the analysis
-
Analysis – an open ended section for writing the analysis. This was typically done in a ‘conversational’ format and was meant to show the individuals thinking through of the problem. It was common for sections of the analysis (especially for bugs) to start with the module name and then have pasted in snippets of code which showed what s/he was looking at and why.
-
Proposed Solutions – another open ended section where the developer had to propose at least two solutions. For a larger project, alternatives for various features may also be discussed. The developer designates one or more alternatives as preferred and provides justification as to why.
-
Traceability Matrix – a table which lists how each requirement was covered by the proposed solution. This was skipped for bug fixes.
The Analysis Review Document
Header:
- Change # (from the analysis document)
- Change Name (from the analysis document)
Checklist:
This section included a set of yes/no questions based upon common mistakes that had been found over time. For example: “Are all sections of the document complete?”, “Does the author provide solution alternatives?” and so on. The checklist was very team specific so I’m leaving off lots of stuff.
Body:
An open ended area for the reviewer to write comments about the analysis. Comments would include things like “I didn’t see module xxx in your examined files section, have you looked at it?” or “Your proposed solution sounds like it requires a massive amount of memory and some of our client systems are quite old” and so on.
Approvals:
This section had 3 check-boxes, the reviewer can choose one: Approved, Approved with Changes or Not Approved. It also had a signature line and a date to indicate when the review was completed.
The Design Document
This document was structurally very similar to the analysis document.
Header:
-
Change ID# – a uniform identifier across all documents to enable tracking
-
Change Name – uniform across all documents to enable tracking
-
Target Release #
Body:
-
Affected Modules – a list of all the modules that were going to be changed. Also whether the module was new or changed was indicated.
-
Design – an open ended section showing the design. Design was done to the pseudocode level. We put a lot of focus on algorithms written in plain English to assure correctness. Where simple enough to do developers often added verbatim lines of code. If inserting new code, the affected snippet of existing code was pasted into the document and pseudocode was added in where appropriate. New code was marked in bold so that the changes were easy to find. The design was always done module by module.
-
Traceability matrix – a section which showed how each requirement was supported by some part of the design.
-
Test plan – the developer inserted test cases for the feature here. These test cases would be used during integration testing to test the product prior to delivery to QA.
The Design Review Document
Like the analysis review document, the design review consists of a header (containing information regarding the change so the documents can be linked together) a checklist of common questions, an open-ended comments section and an approvals section. Checklist questions included:
-
“Does the design meet all the requirements?”
-
“Is the design maintainable?”
The Code Review Document
This is also very similar to the analysis and design review documents. Key checklist questions were:
-
“Is everything in the design reflected in the code?”
-
“Is everything in the code reflected in the design?” We allowed developer to change code if they felt it was appropriate, but they had to go back and update the design. This became significantly easier once we had installed a superior source control tool which allowed you to see all the code changes linked to the change identifier.
-
“Is the code properly handling null pointers?”
-
“Is the code readable?” We did not have specific coding standards, but your code had to be readable. It was a bit of a judgement call, but typically we insisted you were consistent on indents, had good variable names and used one way of placing the curly braces.
-
“Is the code adequately commented?”
Process Optimization
At a higher level, I would produce a post-mortem document for every release we put out to the field. The post-mortem would do a review of all the defects, time lines, rework loops and make an assessment about what could have been done better for that release. If I observed a pattern of behavior across several post-mortems only then would I adjust the process, review checklists or other things in order to compensate for the issue. The major difference between my decision making and what I observe in many organizations is that one screw-up (no matter how bad) does not mean that every project in the future should pay the cost to avoid making that mistake again via a process change. There must be some judgement made as to whether the problem that occurred was really a fault of the process or simply a fault of the person doing the process.
Summary
So, there you have it, a minimalist waterfall process that I found to be very successful in the organization I was in. This process benefited greatly from shifting from a paper based process (where every document was printed and saved in a release binder) to automation via MKS Integrity Manager and MKS Source Integrity. Besides being good for the environment by eliminating virtually all the paper we were printing it also provided an enormous amount of additional project/process detail that I could leverage. In the end, I even had a dashboard I could glance at to tell me where my management effort was needed that day.
