5 The Language of Software Engineering

The goal of this chapter is to present how the concepts discussed in the previous chapter are expressed as a language similar to how a programming language is expressed in computer science. Thus, we learn the concepts of alpha, alpha state, work product, activity, activity space, competency and pattern and how they are expressed.   The reader will be able to

  • explain the language constructs of Essence.
  • explain the role of alpha states in two alphas and related checklists
  • explain the meaning of essentializing a practice
  • explain at an abstract level the role of essentializing a practice

What you learn here provides the necessary handles to use Essence in practice!

5.1 A Simple Practice Example

Essence provides a precise and actionable language to describe software engineering practices. Just as there are constructs like nouns, and verbs in English, there are constructs in the Essence language in the form of shapes and icons. Just as a child learns a language by first using sentences without understanding the underlying grammar, we will introduce the Essence language through a simple practice – a simple pair programming practice. We choose this very simple practice because it is easily understandable even for new students to software engineering. We will introduce more sophisticated practices in later parts of the book.

We describe this programming practice as follows:

  • The purpose of this practice is to produce higher quality code. In this case, we assume that the concept of code quality as being understandable by the different members of the team.
  • Two persons (students) work in pairs to turn requirements into a software system by writing code together.
  • Writing code is part of implementing the system.

Essence categorizes the shapes and icons as the Things to Work With, the Things to Do and Competencies. We shall describe each in turn and at the same time demonstrate how Essence provides explicit and actionable guidance. This actionable guidance is delivered through associated checklists and guidelines.

Figure 16 shows the elements in our simple programming practice. The shapes and icons are the constructs, i.e. the nouns and verbs, in the Essence language.

 

Figure 16       Simple Programming Practice Described Using Essence Language

The different shapes and icons each have different meaning. We will go into greater depth for each one of them and explain their significance. However, let’s quickly enumerate these shapes and icon as in Table 1.

Table 1           Essence Language as used in our simple programming practice.

5.2 The Things to Work With

The things to work with in our programming practice are requirements, software system and code. Essence distinguishes between elements of health and progress versus elements of documentation. The former is known as alphas while the latter is known as work products. Alphas are the important things we work with when conducting software engineering activities. They have states to help practitioners evaluate the progress and health of their endeavor. Work products are the tangible things that practitioners produce when conducting software engineering activities, such as requirement specifications, design models, code. In TravelEssence, the work products include for instance user story index cards, use case narratives, deployment scripts.

Alphas are not work products. Alphas are things we want to track the progress of. An alpha is not tangible by itself, but it is understood or described by the work products that are associated with it and thus describe different aspects of the alpha. Alphas have states to determine how far in the lifecycle the alpha has progressed.

Work products are tangible things such as documents, which can have different levels of detail. In a software development endeavor the degree of detail needed in work products can vary greatly dependent on many factors such as past history of team members working together, customer requirements, regulatory requirements (e.g. regulations for software validation of medical devices) and organizational policies. Let’s give an example. Take Travel Essence for example, Smith’s team express requirements in through Use Case narratives, which we will go into much detail in part 3. Use Case narratives have different levels of detail. For simple requirements, Smith’s team did not need much detail, but relied on more direct communication with their stakeholders. However, for more sophisticated requirements involving complicated calculation and decision rules, Smith had more detailed explanations in his Use Case narratives.

Practitioners often have trouble figuring out how detailed the various work products they produce should be. This is an example where explicit practices can help. To address this challenge, an explicit practice can provide guidance on selecting an appropriate level of detail for related work products.

5.2.1 Alphas

Alphas are subjects in a software endeavor whose evolution we want to understand, monitor, direct, and control. In our programming practice example, Requirements and Software System[1] are alphas. Why are they called alphas? The developers of Essence in searching for a word to describe these important key elements chose the word alpha, which has been used to denote important elements such as “denote position in social hierarchy” or “a star is the first (typically the brightest) star in a constellation” (from Wikipedia). The alphas bound the work to be accomplished in progressing toward the provisioning of the software system. Alphas are portrayed as a stylized variant of the first letter of the Greek alphabet (see Figure 16 and Table 1).

There will always be requirements, regardless of whether you document them or not, or how you document them, e.g. as requirement items, test cases, user manuals, etc. Similarly, there will always be a software system regardless of techniques used and documents produced. Simply put, alphas are the most important things you must attend to and progress in order to be successful in a software development endeavor. In our example of a simple programming practice, there are two alphas, namely: Requirements and Software System.

In some cases, the requirements for a software system may just exist in the heads of people. However, an alpha may be made evidenced by providing one or more descriptions; that is, by attaching work products to the alpha. It is not always needed but very often desirable, in particular for larger endeavors. An example of a Work Product for the Requirements alpha might be some kind of a requirements specification – a description of the requirements of the software system to be built. As a student working on a programming assignment, the programming assignment worksheet is an example of a tangible work product.

Software System is another example of an alpha, which has a Work Product that is code. Code is the physical thing that you as a developer write. The computer processes the code into a software system. The software system itself is intangible whereas the code is tangible.

Alphas have states that describe progression through a lifecycle.

5.2.2 Alpha States

As mentioned earlier, an alpha is not tangible by itself, but it is understood or evidenced by the work product(s) that are associated with it and thus describe a particular aspect of the alpha. In the case that the alpha doesn’t have any work products associated with it, there must be tacit knowledge associated with it.

As an example, Essence defines the states of the Requirements alpha as follows:

  • Conceived – The need for a new system has been agreed.
  • Bounded – The purpose and theme of the new system are clear.
  • Coherent – The requirements provide a consistent description of the essential characteristics of the new system.
  • Acceptable – The requirements describe a system that is acceptable to the stakeholders.
  • Addressed – Enough of the requirements have been addressed to satisfy the need for a new system in a way that is acceptable to the stakeholders.
  • Fulfilled – The requirements that have been addressed to fully satisfy the need for a new system.

To help remember the states of the Requirements alpha, Essence provides a poker-card description as shown in Figure 17. As we will discuss later, such poker-sized cards will also serve as teaching tools, and even make software development more fun through games.

Figure 17       Requirements alpha

Let’s consider the layout of the card. At the top left you see the icon representing an alpha. This distinguishes it as an alpha card rather than a work product card, competency card, or any other element. The top of the card also highlights the name of the element, in this case, the Requirements. This is followed by a brief description of the alpha and the states of the alpha. This is a very concise overview of the requirements alpha. For more details refer to the Essence specification.

Cards are also available for each alpha state as shown in Figure 18.

 

Figure 18       Requirements Alpha State cards

There are 6 cards in Figure 18, one for each of Requirements alpha states. The layout of each card comprises the alpha icon and the alpha name at the top, followed by the alpha state name, and the checklist criteria for achieving each alpha state. The checklist criteria are not expressed formally so teams can interpret each checklist item as they deem it appropriate to their endeavor. This was done intentionally so that each team would be able to consider what the checklist item meant within their own team context. At the bottom of the card there is a bar indicating the sequence number and the total number of alpha states for this alpha. The checklists on the alpha state cards are abbreviations of the full checklists specified by the standard. They were made to make possible putting the checklists on the cards for ease of quick reference.  In some cases, the abbreviations may not be fully understandable.  In those cases, you should read the full checklist. The full checklists are available in the Essence Quick Reference Guide which is available for download from the www.software-engineering-essentialized.com. 

In our example, the Software System is also an alpha. It has the states shown in Figure 19.

Figure 19       Software System card and states

The states are defined on the basis of an incremental risk driven approach to building the Software System, first by establishing a sound architecture, and then demonstrating key decisions about the Software System. These states are summarized as follows:

  • Architecture Selected – key decisions about the Software System have been made. For instance, the most important system elements and their interfaces are agreed upon.
  • Demonstrated – key use of the Software System has been demonstrated and agreed.
  • Useable – the Software System is usable from the point of view of its users.
  • Ready – the Software System has sufficient quality for deployment to production, and the production environment is ready.
  • Operational – the Software System is operating well in the production environment.
  • Retired – the Software System is retired and replaced by a new version of the Software System, or by a separate Software System.

5.2.3 Work Products

As described previously, work products are tangible things such as documents and reports. Work products may provide evidence to verify the achievement of alpha states. For example, when a complete and accepted requirements document has been developed that evidence can be used to confirm achieving certain checklists within a state of the Requirements alpha.  The fact that you have a document is not necessarily a sufficient condition to prove evidence of state achievement. Historically, documentation has not always provided an accurate measurement of progress. Thus, you may reach the same state without any documentation or with very brief documentation as long as the checklist for that state has been achieved satisfactorily.

Code is an example of a work product for our programming practice. We provide a concise description of this work product in the form of a poker-sized card as shown in Figure 20.

Figure 20       The Code work product card

Note that the work products you produce do not belong to the common ground represented by the Essence standard. They are dependent on how you want to work (which practices you want to use). Thus, Essence does not specify specifically which work products are to be developed, but it does specifically specify what work products are, how you represent them and what you can do with them.

5.3 Competencies

The team members applying the programming practice must, of course, be able to program; that is, they must have a development competency. Competencies are the abilities needed when applying a practice. Often software teams struggle because they don’t have all the abilities needed for the task they have been given. In these situations, a coach can help by explaining different ways the practitioner can address the problem, such as learning something that is missing in their competencies.

Figure 21 shows the card for the Development competency. Similar in format to the alpha and work product cards, the top of a competency card has the competency icon and the competency name followed by a very brief description of the competency. Below is a list of competency levels.

Figure 21       The Development competency card

The Development competency has five levels of achievement:

  1. Assists – Demonstrates a basic understanding of the concepts and can follow instructions.
  2. Applies – Able to apply the concepts in simple contexts by routinely applying the experience gained so far.
  3. Masters – Able to apply the concepts in most contexts and has the experience to work without supervision.
  4. Adapts – Able to apply judgment on when and how to apply the concepts to more complex contexts. Can enable others to apply the concepts.
  5. Innovates – A recognized expert, able to extend the concepts to new contexts and inspire others.

A useful exercise that teams are encouraged to conduct is to do a self-assessment of their competencies and compare the results to the competencies they believe they need to accomplish their specific endeavor. This exercise can help software teams objectively determine any competency gaps they may have which they can raise to management for resolution before serious problems occur that could hurt their team’s performance.

5.4 Things to Do

To make progress in a software engineering endeavor, or for that matter, any endeavor, participants must do something. In our programming practice, this is about writing code. The Essence language calls this an activity.

5.4.1 Activities

Activities are things which practitioners do, such as holding a meeting, analyzing a requirement, writing code, testing or peer review. Similar to the challenges practitioners often have with determining the appropriate level of detail in work products, they also often struggle to determine the appropriate degree of detail or formality with an activity, or exactly how to go about conducting the activity. This is another motivation for explicit practices as they can provide guidance to practitioners in selecting appropriate activities as well as provide guidance in how to go about conducting each activity. A practice may include several activities that are specific to the practice being described. Thus, activities are specific and not standard – they are not a part of Essence. Figure 22 shows the activity card for Write Code. The activity space concept will be described in the next section.

Figure 22       The Write Code activity card

An activity is always bound to a specific practice, it cannot “float around” among the practices. If you find an activity that needs to be reused by many practices, then you may want to create a separate practice including this activity. The alternative is that you decide not to reuse it, but each practice that potentially could have reused it will have to keep its own copy of that activity. Changes to one copy of it will not impact the other copies; they will just change independently of one another, which means no reuse.

5.5 Essentializing Practices

What we have presented above is a simple approach to concisely describe a practice, in this case a simple programming practice. We call the approach essentialization. Essentialization makes use of the Essence language, which we summarize in Figure 23.

 

Figure 23       Elements of the Essence Language and their relationships

As you can see the language contains two more elements – activity space and pattern - than introduced thus far. See Table 2. These elements will be described deeper in the next chapter. The syntax and shape of these elements are defined in [1].

Table 2           Additional elements in the Essence Language

Alphas are the essential things we work with. Each alpha defines a lifecycle moving from one alpha state to another. Work products are the tangible things that describe an alpha and give evidence to its alpha states. Activity is required to produce or update a work product. Activity spaces organize activities. To conduct an activity requires specific competencies. Patterns are solutions to typical problems. An example of a pattern is a role, which is a solution to the problem of assigning work.

Essentializing a practice follows the following steps:

  • Identifying the elements – this is primarily identifying a list of elements that make up a practice. The output is essentially a diagram like that in Figure 16 at the beginning of this chapter.
  • Drafting the relationships between the elements and the outline of each element – At this point, the cards are created.
  • Providing further details – Usually, the cards will be supplemented with additional guidelines, hints and tips, examples, and references to other resources, such as articles and books.

In the rest of this book, especially in part 3, we will provide more examples of essentialized practices.

What should you now be able to accomplish?

After studying this chapter, you should be able to

  • identify the concepts of alpha, alpha state, work product, and how they are expressed. 
  • identify the concepts of activity, activity space, and how they are expressed. 
  • identify the concepts of competency and pattern, and how they are expressed.
  • identify cards as a practical way to use the various language elements of Essence
 

[1] In this book we have adopted a convention for the use of lower-case letters vs capitals. Lower case letters are default for Essence language constructs such as practice, alpha, alpha state, alpha card, work product, level of detail. However, when referring to names of elements defined in the Essence language we use an initial capital letter. Examples are names of alphas (Requirements, Software System), alpha states (Requirements: Conceived), work products (Use-Case Narrative), level of detail (Outlined).
Italics are used independently, only to provide emphasis.