Insight Consulting Ltd.
Process documentation – asset or liability?
A significant risk to successful Software Process Improvement (SPI) is going overboard on the documentation of your processes. Many of you will have encountered the folders of procedures gathering dust on shelves. Sometimes it is the sheer volume of this documentation that turns people off (or indeed the energy that is sapped from the improvement effort in writing them). Other times it is the poor usability of these documents – it takes too long to get useful information, or the needs of different types of ‘users’ of the documentation are not taken into account e.g. smaller projects. Often, because of maintenance difficulty, it the fact that the contents do not match actual practice further reducing the credibility of ‘process’ and its improvement.
This problem is driven in part by management often mistaking documentation for real progress… ‘it’s written down so we’re finished, aren’t we?’ Process, however, is best defined as ‘what people do’. This is the end game, not the documentation.
So how do we avoid these problems and develop lean, flexible and above all useful process documents? Firstly, be remembering the end game – the emphasis needs to be on the ‘doing’. Therefore putting effort into coaching and mentoring people rather than developing volumes of process documents is clearly a better strategy. The temporary skills or knowledge gap present when introducing a new/improved process is addressed more effectively by practical training approaches rather than handing someone a 30-page process document! Therefore, the objectives of process documentation should not include training.
We still need process documents but the reason for writing them is not to provide a repository for a brain dump on the part of the author(s). The key to effective writing is considering the needs of the reader. The person performing the process needs to be reminded what to do and how to do it. This is one objective. The other key objective is to obtain agreement with the various stakeholders on the process itself. The process documentation provides this definition of consensus. With these as your two key objectives, a process can be defined in one or two pages.
From a usability point of view we also need to consider the architecture of our process definition. The higher level ‘process’ is ‘what to do’, the lower level ‘procedure’ is ‘how to do it’. For example, a step in the project planning process would be to estimate size, a procedure for estimation size would define how to do this in terms of estimating lines of code or function points or pages or requirements, etc. We only define procedural elements when further definition on how to do something is required. Examples of lean process definitions will soon be available on the Insight Consulting website.
By distinguishing between process and procedure we can also address the other problem of inflexibility. We only need projects to be following the same process – they can each use their own procedures (CMM level 3 for example only requires institutionalisation at the process level). By not forcing projects to follow one procedure we resist the temptation of over standardisation. As an organisation matures, we can of course reduce the number of allowable procedures to create more standardisation. These procedures have then been proven to work well for certain types of projects and we can avail of the benefits of standardisation such as organisational-wide metrics. Too much standardisation too soon results in resistance from staff and overly rigid and inflexible practices.
I recently worked with one organisation that managed to define their entire Software Configuration Management (SCM) process in a page. The process definition included bullet points under the following headings: inputs, entry criteria, tasks, exit criteria, outputs, roles and measurements. The process in turn referenced 10 one to two page procedures for more detail on key process steps such as SCM planning. Sample procedures were developed but projects were free to develop their own. Templates and checklists supported the process definition.
In summary, keep your process definition lean and flexible by
- Removing training as an objective of your process documents.
- Distinguishing between process and procedure in your documentation and resisting the temptation to standardise on procedures too soon.
Usability will be further enhanced by having a web-based deployment of your process documents and employing graphical views, especially at the process level.
2002 Insight Consulting Ltd.