Literate Process Modeling

Comments: 1
Rate this:
Total votes: 0

Thirty years ago, Donald Knuth introduced the notion of literate programming.   He wrote “Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.”   His premise was that over the lifetime of any successful program, far more hours would be spent reading it for purposes of maintenance and enhancement than were originally spent creating it.  Furthermore, most of this would be by people other than the original author.  If this is true, a little more effort in documentation by the original author will be paid back many times.  We believe these principles are even more important in Process Modeling than in traditional programming. 

Many vendors don’t like to admit this, but an executable BPM process model is a computer program.  It is a set of instructions which direct the actions of the system.  It is defined largely in a graphical notation and uses constructs which are closer to the business domain than the computer, but it is still a program.  More so than traditional programming, BPM methodologies embrace continuous improvement.  Since the process model is easy to modify, the barriers to change are lower and organizations should take advantage of this to continuously improve their business.  To be successful, this requires that process models be easy to understand and to modify.  Unlike traditional programming, the business stakeholders will interact directly with the “program code”, the BPMN model.  This requires that the model be created not only for execution by the computer and understanding by technical professionals, but also for correct understanding by business people with limited training and understanding of the modeling notation. 

We have found that one of the more common causes of failure in BPM projects is that when a process is deployed to production, its behavior does not match the expectations of the business users.  This can occur even when business users are involved throughout the full development lifecycle.  They review and approve process models based on a limited understanding of the behavior of the various modeling elements.  In the extreme, this causes a loss of confidence in BPM as a strategy and death of the BPM initiative.   The gap in precision of model comprehension will never completely disappear, but there are ways to reduce it.  Borrowing from Knuth, we lump these practices under the label Literate Process Modeling.  The rest of this article will discuss practices which facilitate literate process modeling.

The first step is for an organization to establish modeling standards.  Every tool is different, and most implement only a subset of the full BPMN standard, so it is not possible to propose a universal set of recommendations.  Each organization must define guidelines appropriate for its tools, business domain and organizational culture.   Defining standards is not enough, they must be enforced.  We have found peer reviews very effective at several stages in the process.  The first review should be early, when the process is perhaps 50% defined.  A final review before deployment is essential.  For complex processes or ones that had many changes additional reviews may be necessary.  This need not be a burdensome process, for a typical process it should only take 10-15 minutes.  A simple spreadsheet checklist is very useful in assisting the reviewer to remember all of the standards.  It should not contain more than 25-30 items.  The act of forcing the author and reviewer(s) to sign-off on the review is powerful in ensuring that the standards are taken seriously and followed.

The second step is training.  Process creators will likely need the vendor’s training on the specific tool, but all stakeholders should be given training in the organization’s modeling standards and the peer review process.  This training should be developed and delivered internally.  Obviously this training must be given near the beginning of the program.  For the initial program and for new team members, we have found it valuable to repeat it in a few months, after everyone has had some hands on experience.  The standards, and particularly why they are preferable to the alternatives will be better appreciated at this time.

As with traditional programming, additional of textual documentation is essential.  In traditional programming languages, comments in the source code are used.  In Knuth’s literate programming platform cweb, this is reversed and the code is interspersed in a descriptive text document.  The primary BPMN support for documentation is the Text Annotation.  Annotations are placed in the process, near the elements they elaborate.  The text is visible without further searching.  In general, annotations should be used to explain anything which is not obvious to the non-expert stakeholder.  Splitting gateways are a good candidate for explanation as are system activities.   We prefer to keep the text of individual annotations fairly short, 15-20 words maximum.  We have seen processes where there were paragraph length explanation of nearly every activity, event and gateway.  In these processes, the annotations took up so much space that they actually obscured the flow of the processes.  We have generally found that a number of annotations in the range of 50-100% of the number of functional elements to be sufficient without crowding out the other elements. 

BPMN is a large, complex standard.  It often includes multiple ways to model the same behavior, and includes some elements whose behaviors are quite opaque.   We find that it is best to pick one and use it consistently.  In choosing between alternative notations, always select the one which most explicitly communicates the intent.   This will often result in a model with more elements, but this is a small price to pay for improved understanding.

 There have been several controlled academic experiments to evaluate the impact of different notations on process understanding.  One common finding is that all behavior should be made explicit.  For example, BPMN allows branching and joining of flows without gateways by having multiple flows in and out of activities and events.  The exact behavior of these is defined by secondary notations for default flows and conditions.  While these are sufficient for the process execution engine and for expert modelers, business people often misinterpret these.   

Process modeling best practices is a topic far too large for a short article such as this one, and we will be exploring other aspects in future articles.  We hope that this has improved your understanding of what is a good process model and that you will begin to apply some of these ideas in your organization.


posted 2 years 46 weeks ago
In short, a very interesting article. For many years I programmed extensively in BASIC (before the Visual/OO era) and less so in COBOL and RPG. When I learned programming techniques in the mid to late 70s (BASIC), my instructors at the time instilled a discipline of including structured, in-line documentation in my programs and that discipline has served me well over the years. In fact, we were taught to 'write out' our solutions in a structured English format (also called psuedo-code). This technique taught us a 'universal way' to write up a programming solution that could (in theory) be translated into any language. BASIC was fairly easy (perhaps too easy) to learn, use and follow but lacked any forced structure - the opposite of say verbose old COBOL. With psuedo-code, we also had the documentation that could be easily inserted in the code as REMarks. The result? This made other people's code very hard to follow (and maintain) at times. In addition, the early versions of BASIC were far more restrictive in naming variables and subroutines, the latter were often limited to line numbers with named subroutines not even possible. In my professional BASIC programming work that followed my school days, I followed my teachings to the letter and produced BASIC language programs that were well documented (perhaps 50% or more of the code was documentation) and were as a result, quite easy to maintain - be it 1 day, 100 days or 10 years on. The simple rule I have always followed is: Say what you're going to do (the comment), do what you said you're going to do (the code). However, this notion of documentation is a matter of style (or personal choice) and the programming languages themselves (save for COBOL) don't really enforce any degree of documentation rigor. As a business analyst/process consultant nowadays, I often invoke my old program documentation training to instill this same sort of regiment in my process modeling work, or when documenting processes and procedures. Some coding tools I've used in the past have included built-in documentation generators - that's certainly a step in the right direction, but these usually focus on end-user side documentation, not on the technical or maintenance side. Other tools have shells that force creation of code in a step by step manner and hence the results can be similarly documented. However, most of these tools were/are rudimentary. As I see it, documentation remains an industry afterthought, when if practiced correctly, documentation should be at the FORETHOUGHT of all coding. Regards, rs

Join the Discussion

Your email address will remain private.

Shopping cart

View your shopping cart.

Related training courses provides training courses online and in person for individuals and groups. View courses related to the material you are reading on this page. 

BPM 101OpEx 101Agile Business Analysis 101Decision Management and Business Rules 101Methodologies and Approaches for BPMView the Learning Path for more courses »

Business Process Management Jobs

Editorial Directors

Gregg Rock
Gregg Rock
Editor & Founder

Andrew Spanyi
Editorial Director

Jeff Scott
Editorial Director