Month: December 2019

There is an old engineering joke(1);

One day, a year after she(3) retires Lucy receives a call from her former boss. “Lucy, the X-43q isn’t working, I know it was your baby, um, could you come in take a look at it?” Grumbling she says “Yes, but I want 10K for the repair”; since the X-43q is key to everything they due and no-one knew what to do(2) they quickly agree. The next day she comes in, listens to the machine for 5 seconds and says “The timing belt is slack, replace the tensioner spring. Check please.”

In shock her former boss sputters, “You can’t expect 10K for 5 seconds of work!”

She replies, “The 10K isn’t for the 5 seconds of work, it is for the 10 years that where I learned what to do”(4)

Attributed to just about every senior engineer….

So to explain the title: If a tree falls in the forest it still makes a sound; however if a process isn’t written down it does exist. So what how do you write up a process?

Objectives, actions, triggers, conditions and rationale

The most basic process document has three parts

1. Objective(s): the outcome of following the process
   • Positive: X shall occur
   • Negative: X shall not occur
2. Actions: what you do to achieve the objective
   • Explicate: The following steps shall occur
   • Engineering judgement: (5) The following types of things shall be done
3. Rationale: why you are taking an action, condition, or modification. There can be multiple rationale for a single process. More complex processes will have more rationale

It is rare for a process document to have just the Objective and the Actions, the two other categories are

1. Triggers: what starts the process in motion
   • Periodic: tasks that are performed on a temporal basis
   • Conditional Event: when X happens the the task starts
   • Process Event: when a milestone in the project is reached
2. Conditions: modifications to the process based on environmental factors
   1. Modifying: if Q happens then follow the “Q” path through the process
   2. Aborting: if R happens then halt the process and start process “Oh crud R happened”
   3. Gating: Before this process can start the following must happen.

The distinction between conditional and process events is simple; process events are expected, conditional events may happen(6).

A short example process

Process for making 3-bean soup (objective: have a tasty meal)

When the number of soups in the freezer falls under 3 (conditional trigger) then a soup shall be made. The type of soup shall be dependent on the last 2 types made (modifying condition) to prevent repetition of the soups (rationale)

Actions:

1. Verify you have 2 hours to monitor the soup (gating condition on the process)
2. Verify you have the required ingredients (gating condition on the process)
3. Chop, dice, mince and mix,
   do the things for soup to fix.(7)
4. O-going: Monitor for soup overheating
   1. Add water or reduce heat (engineering cooks judgement)

With step 4 I introduce the notation “on-going”. With in a process some steps are one-off and others are on-going or repeated. In context it should be obvious why something falls into a given category

Footnotes

1. Like most, it isn’t funny, it is bitter. Engineering jokes are like Aesop’s fables, they attempt to impart wisdom but we are often left wondering “if the mice have metal working technology to make a bell, why don’t they make some arms and weapons”(2)
2. At least that is what I wondered.
3. I’ve updated the old joke
4. Of course if they had given her time to write up what to do she could have stayed retired
5. There will always be some engineering judgement in processes, the goal is to guide that judgement
6. We can use a simple cooking analogy. When you are making dinner you expect the food to finish cooking, that is a process trigger, e.g. set the table. You do not expect the food to catch on fire in the oven, that is a conditional trigger.
   1. One day I will start a blog “MBC : Michael Burke Cooks” for now accept a short rhyming couplet for what goes into making a soup (or anything else)

In this post I argue for performing simulation instead of model differencing to examine changes to a model. So take a deep breath(0) as I’m about to push this analogy fairly hard… When I’m in the kitchen creating a meal I take care with my ingredients, checking for freshness and the flavor balance (1), always aware of allergy issues(2). I start in a clean kitchen(3), I use a sharp knife and a cast iron pan on a gas stove, quality tools(4). When the dish is done I plate it and I judge it by how it looks and how it tastes. When it is done it is judged by what it is, not what went into it.

By contrast when I balance my checkbook(5,6) in each line item is inspected for correctness and the desirability of the transaction; to understand my finances I need to know each transaction.

A good model is rather like bouillabaisse(9), a complex harmony where the sum is greater than the parts; so then how do you “taste” a model? If you are working in a Model-Based Design environment(10) it means simulating the model and inspecting the outputs of the simulation. If the simulation shows the model is behaving in the expected way for a given scenario, then you know you have the “right” taste. This is a functional review.

“But wait”, you may be saying(11), “what about allergies, a clean kitchen and good tools”? These are addressed by processes and guidelines. Processes protect you from allergies by enforcing guidelines (12), test driven development (13) and development based on requirements (15). The clean kitchen, well that comes from following good processes for an extended period of time; and like any good chief would tell you, “if you are not cooking you should be cleaning”. Good tools, well, see The MathWorks.

“Ok, so I see why be a cook, but why not an accountant? Don’t I need to double check things?” You may be pondering (16). Accounting comes into play if you don’t pass the taste test and if those tests don’t identify the root of the problem. Then performing a block-by-block (or line-by-line) review of model is realvant. Until then doing a model or code differencing does not provide utility.

If I have an equation, say 2+2, and then you change it to 2+3, it is easy for me to see the difference in the outcome by comparing the text. However if this is my equation

The effect of a small change is not obvious by inspection. Differencing text and differencing models is a methodology held over from a time before easy simulation when it was one of the few ways to figure out what was happening. This accounting approach is still valuable as a debugging tool but it is not and should not be your primary method for reviewing models.

Disclaimer: this maybe the first post where the footnotes are longer than the article. I got carried away. I blame Terry Pratchett (17).

Footnotes

This is where I show just how much I can push this analogy:

1. Deep breath: Note if you were in the kitchen while I was cooking that deep breath would be delightful, unless I’m pickling, pickles taste great but brine air is not fine air.
2. Freshness & flavor balance: In software this I validate “am I using the most up-to-date methodologies” and are those methodologies the correct for this project.
3. Allergies: Are a stand in for the know issues in development, either bugs or requirements that need to be met.
4. A clean kitchen: clearly this is a plea to start your development process with a minimum of legacy issues.
5. Quality tools: There is an old cooking saying “The sharper the knife the safer the knife”. Quality tools prevent some category of errors and make it easier to prevent others.
6. Checkbooks: For those under the age of 25, checkbooks are a primitive form of tracking payments in which the writer of a check recorded the amount of the promissory note (check) and subtract that from a banking balance.(7)
7. Checkbooks 2: Technically speaking out online spreadsheet that collates information for statistical analysis.
8. Checks/Balance: This is not to be confused with the concepts of checks and balances that is baked into the US constitution.
9. Bouillabaisse: With the hint of Safron that pulls it together.
10. MBD Environment: If you are not already working in this environment, hopefully this blog gives you reasons to do so.
11. May be saying: I am assuming you are very invested in this blog post and can’t help but verbally exclaim your concerns as you read it. Please be aware of the people around you.
12. Guidelines: Modeling guidelines are like cooking best practices; codified common knowledge.
13. Test driven development: In the same way you press on a burger to know when it is done (14) test driven development makes sure your code is well-done.
14. Press down on the burger: This would be considered black box testing since you are not cutting into the burger.
15. Requirements: Requirements are like recipes; they are what you start with and you may have to evolve over time. Rational evolution leads to tasty dishes, random substitution leads to the garbage disposal.
16. Pondering: Doing this after 11, and noticing the people around you.
17. Terry Pratchett (Sir): https://en.wikipedia.org/wiki/Once_More*_with_Footnotes