Software Process Descriptions

What you should observe when you
define a Process

I want to give you a few hints on this page about writing a good process description. First of all you should think about the overall structure of your procedures, guidelines and templates. For your domain you should establish a single main procedure. Usually this is enough to describe everything that is necessary to perform your work. A domain is to be regarded an own working group or department as e.g. software development or hardware development. It may be legitimate to write an overall procedure for e.g. all product development in a company, but this has to be a wrapper procedure, showing the interactions and interfaces, but not more. Do not attempt to cover more than one domain in a detailed procedure.

Furhter there is the possiblility of having sub-procedures within a domain. This is always the best choice if you want to describe a separated dedicated activity. An example for this may be a test procedure. If you are lucky and have an own test team or department you should give them their own sub-procedure, unless their activity is too small, so that it makes no sense to have a dedicated paper.

A procedure or process description should describe the "who does what when" of the activities. However there may be the need to describe how an activity is performed. This should be described in a Method. E.g. you should not describe the details of how you perform testing in the procedure. This has to be done in the method.

Further there will be work products i.e. documents or source code coming out of your process steps. For these defined work products you have to provide templates which can be used and filled in by the employees as they perform the process steps. The following picture gives an overview of a possible procedure landscape. The arrows show which document usually references another document.




To summarize this we could say:

Make a proper design of your process landscape. There should be procedures which describe WHO does WHAT, WHEN (i.e. in which sequence). This should be not too detailed. Only high level with a clear naming of inputs, outputs and roles. Then define methods (may be also called guidelines) which describe in detail HOW things are done. These should give technical details and advise what has to be done in different situations. These are hard work to be established and need a deep knowledge of the technical details. This means, to set up these guidelines, process engineers may need assistance from people who actually do the technical work. Define templates for all work products and assisting documents named in your process. It should never be left to chance how a document will look like. It needs your company's logo, a copyright or non-disclosure comment, a clearly defined structure and content.

Next I want to go a bit more into details about the structure of a procedure. It is always a good habit to visualize your process before you go into more detailed descriptions. This can be done in a simple flowchart manner like shown in the following picture:



After the visualization you should describe each of the process steps in detail. It is recommendable that you use a template for this, so that each of the process blocks will be described in the same manner as shown on the following example:



Finally I want to summarize the main features of a good process description:

Each process step has to have a unique identification number as e.g. the "SWD1" (standing for Software Development 1) in the above example. It is much easier to refer to "SWD1" than to talk about the "requirements engineering in the development phase". Especially if you have more complex processes with e.g. multipe object reviews at different places a unique ID will be always better to talk clearly and precise about process steps. Each process step has to have a goal. E.g. to establish, update or review a certain work product. This goal should be clearly defined. Each process step you define has to have a clearly defined input. If this is a document established somerwhere else in the process you should refer to its template and the process step ID in which it is generated. But there may be also external documents as e.g. customer specifications which may serve as an input. Even more important, a process step should have a clearly defined main output (e.g. a document, an integrated software package, etc.). It is o.k. if there are supporting documents as additional outputs, like a checklist or comment list, but never have more than one main work product as an output of a process step. Further, if it does not have a clear output you should reconsider this process step. There has to be the generation or update of a document, a source code, any kind of defined work product in a defined quality which should come out of a process step. Never ever decribe a step like "check the source code of the other colleague" this is no good. The following would be o.k. "perform a source code review on the source code using the check list xxxxx and write the results into the review report document using the template yyyyy". Describe the actions or activities of each process step in more detail in the sense of "what has to be done" and assign it to a role. It has to be clear who has to do this activitiy. It may be necessary to name more than one role. In this case one role has to be the leading and reponsible one and the others are participating. Never make more than on role responsible for a certain activity. Always be precise in your wording. Write down what is expected to be done, what is the output and what do you do with the output. This may be a "check in" into a version management archive, and it may need a notification of somebody or a signature of a responsible, etc. Always provide templates for each work product or supporting document and reference them in the process steps. You must not leave it up to chance how the document will look like. It has to be clear which documents shall be generated. Define and describe clearly all roles in the process. Never leave it undefined who will perform certain steps in the process. A role is a responsibility, describing the work a responsible person has to do in the process. Never use actual names of persons. They might not be in the company any more before the ink on your procedure is dry. Describe roles like "Software Designer", "Software Tester". Later on the management has to assign actual people to these roles. You should also be aware that it may make sense to describe roles although you already know that there will be actual persons who will take on multiple roles. Refer to any methods, guidelines or standards which are necesary to perform the process step. These may be your internal methods i.e. decriptions of "how" things have to be done, but also general or public standards which need to be considered.

If you need assistance in your process definitions feel free to contact me. I have many years of experience in software process definition and improvement. I have suffered myself at times from too heavy processes. I can assist you to achieve lean processes which help your work rather than hindering it. This will include the analysis of existing processes even if they are not written down so far, it will include the definition of your processes, writing methods and set up of templates, trainings, etc. I also have a set of general templates and a procedure which match most software development processes. Contact me if you want to have them. They can be a great help and starting point for your own proceses.