Chapter 5 — Engineering communication

Chapter 5 — Engineering communication

Lesson map

Lesson 05 published. Map, example, EX013.

flowchart TD
  N0["Learning outcomes"]
  N1["5.1 Writing for readers"]
  N2["5.2 Explaining trade-offs"]
  N3["5.3 Decision records"]
  N4["Synthesis"]
  N0 --> N1 --> N2 --> N3 --> N4
  N4 --> EX["Worked example"]
  EX --> Q["Exercise EX013"]

Logical drawing

flowchart LR
  N0["Learning outcomes"]
  N1["5.1 Writing for readers"]
  N2["5.2 Explaining trade-offs"]
  N3["5.3 Decision records"]
  N4["Synthesis"]
  N0 --> N1 --> N2 --> N3 --> N4 --> Q["EX013"]

[Learning outcomes]
    |
    v
[5.1 Writing for readers]
    |
    v
[5.2 Explaining trade-offs]
    |
    v
[5.3 Decision records]
    |
    v
[Synthesis]
    |
    v
[Worked example] --> [Exercise EX013]

Learning outcomes

You will (1) write requirements and reports clearly; (2) explain blockchain trade-offs to non-specialists; (3) record decisions.

5.1 Writing for readers

Jonas must explain technical choices to the cooperative's board, which includes a retired teacher, an electrician and an accountant. He learns to start with the decision needed, then give the options, the trade-offs and his recommendation in plain words. He avoids jargon or defines it once: a smart contract is a program stored on the ledger that runs automatically when called. A short, clear note respects readers' time and helps them make good decisions, which is the purpose of engineering communication.

5.2 Explaining trade-offs

The board asks whether the system should use a public blockchain or the cooperative's own permissioned ledger. Jonas explains in a table: a public chain offers wide independence but exposes transactions publicly and costs fees; a permissioned ledger is cheaper and private but relies on trusting the node operators. He cites NIST IR 8202 for the distinction. He states his recommendation, the permissioned ledger with published governance rules, and the conditions under which he would change it. Honest trade-offs build trust more than confident promises.

5.3 Decision records

Jonas keeps decision records: short notes stating the decision, context, options considered, the choice and its consequences, with the date and who approved it. The first records the ledger choice, the second the use of integer amounts. Months later, when a new board member asks why the system is not on a public chain, the record answers in two minutes. Decision records preserve reasoning across years and people, which matters in a five-year project and in security, where forgotten reasons lead to unsafe changes.

Worked example

Jonas presents a one-page trade-off table to the board, who approve a permissioned ledger with published governance; the decision is recorded.

Synthetic case. Board members and decisions are synthetic; NIST IR 8202 is a real source.

Errors and limits

Presenting only the recommended option without trade-offs denies decision-makers the information they need.

Exercises

• EX013 — Note structure. How does Jonas structure board notes? Rubric: 3 = decision, options, trade-offs, recommendation;; 2 = decision first;; 1 = jargon;; 0 = none.
• EX014 — Ledger recommendation. What did Jonas recommend? Rubric: 3 = permissioned ledger with published governance;; 2 = permissioned;; 1 = public chain;; 0 = none.
• EX015 — Record value. How did a decision record help later? Rubric: 3 = answered a new member's question quickly;; 2 = reasoning preserved;; 1 = vague;; 0 = none.

Synthesis

Clear writing, honest trade-offs and decision records make engineering choices understandable and durable.

Continue studying — chapter 05 of 50

← Chapter 04 (draft) · Course chapter index · Chapter 06 (draft) →