In many implementation and development methodologies, the concept of an issue list is prevalent and in many cases considered a critical component of managing a project. This list is used to identify and track progress to closure of many different "issues" on the project including decisions by the business, detailed design or requirements questions, managment issues, etc. The format and content of the lists vary as does the content of the lists. Are these lists a critical component of managing a successful project or are they are common misconception that leads to unstable technical baselines and the downside of scope creep?
This post will examine this question. First, let's define some terms for the purpose of discussion.
Issue list - a set of questions, concerns, decision points that require resolution and specifically do not include issues found during the testing cycles which are commonly referred to as defects, bugs, trouble report, software trouble reports, etc.
Technical baseline - a set of documents that uniquely describe both the requirements including business, technical, functional, and non-functional as well as the detailed technical designs on how to either develop software or enter meta data into a previously built commercial software package.
With these defintions in mind, the question remains are issue lists a good thing?
One of critical aspects of managing a project is to understand the requirements, devise a strategy and plan for building the solution, then defining the solution to be built. In the agile methologies, the order may be different but in all cases there is a starting point for developing software or implementing a commercial package. When this starting point changes, the solution may change which we all know tends to extend the schedule even when we plan for that change as with agile. This technical baseline becomes the guide.
A second critical aspect of managing a project is defining and maintaining this technical baseline. When we create multiple documents which define the baseline, we create a situation whereby many documents have to remain in synchronization. The difficulty of this situation increases expontentially as the number of documents in the technical baseline increase. In a typical waterfall project, we have a requirements document and a small number of detailed design documents for solution components like interfaces, custom software, maybe some user exits, etc.
What happens when we write let's say a interface design. Parties get together to review said document and identify a set of issues which we might maintain in an issues list. Perfect, right.... Well maybe not... The next logical step is to work the issues including status updates and proposed resolutions. Eventually, we get the resolutions completed and documented in the issues list.
Now we have to go back into the detailed design document and integrate the issue resolutions into the design. This seems unwieldy and redundant... If we don't go back and integrate the issues resolutions with the design, we end up with a detailed design which has some of the design and a series of issue which have other parts of the design. Even in an agile approach as the customer comments begin to mount, who and how does the project manager ensure all the issue resolutions are consistent and included in the solution. How does it all fit together then becomes a problem. In many cases during an agile project, the solution is the consolidated set of resolutions and a single location in which to look for the latest baseline.
Worst still is someone who is not familiar with the design has to read the design and all the issues which may apply then determine how they think the issues and design fit together which may or may not be the same interpretation as every one else. These leads to confusion and an undermining of the technical baseline.
So what is a better way to handle? In my experience, if something is important enough to make an issue, it should be recorded in some document that is part of the technical baseline. This could be a requirements document, interface design, software design, etc. When issues are defined, they are in context to some language in one of the technical baseline documents or is new language that should be in such a document.
Given this is true, how about maintaining the issues within the documents. Most modern word processing or spreadsheet applications have a comment feature so issues can be documented in the actual documents. If an issues arises with Section x.y of the document, the individual identifying the issue enters a comment at the sentence(s) where the issue arises. The side benefit is there is no need to define pointers into the source document or confusion around what langugage is being questioned as exists with an issue list as the pointer to the document and page must be included in the list. This can be cumbersome and confusing in its own righ. These issues are then worked in context to the overall design and language is integrated into a single document.
One downside to this approach. Many project managers like to have a consolidated set of issues they can work and this solution makes that difficult. I would suggest the upside to maintaining a stronger technical baseline far outweighs the extra effort required to manage through the technical baseline. In a future post, I will discuss the concept of managing by lists.
The last point is there are a set of management activities commonly included on an issue list that should remain in a separate and consolidated list. These issues include management activities not directly related to the solution. Issues such as lack of VPN access, or developer needs a physical access badge for the building, visas needs to be approved, individual staff needs counseling, etc. These issues are appropriate and I typically track as part of a periodic status report.