Chapter 5 — Engineering communication
Lesson map
Lesson 05 published. Map, example, EX013.
flowchart TD
N0["Learning outcomes"]
N1["5.1 Audiences"]
N2["5.2 Diagrams"]
N3["5.3 Trade-off tables"]
N4["5.4 Plain language"]
N5["Synthesis"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5
N5 --> EX["Worked example"]
EX --> Q["Exercise EX013"]
Logical drawing
flowchart LR
N0["Learning outcomes"]
N1["5.1 Audiences"]
N2["5.2 Diagrams"]
N3["5.3 Trade-off tables"]
N4["5.4 Plain language"]
N5["Synthesis"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> Q["EX013"]
[Learning outcomes]
|
v
[5.1 Audiences]
|
v
[5.2 Diagrams]
|
v
[5.3 Trade-off tables]
|
v
[5.4 Plain language]
|
v
[Synthesis]
|
v
[Worked example] --> [Exercise EX013]
Learning outcomes
You will (1) write for different audiences; (2) draw identity architecture diagrams; (3) explain trade-offs in plain language.
5.1 Audiences
Different readers need different things from the same identity design. Council directors want risk, cost and disruption in plain terms; service desk staff need to know what changes for callers; application owners need integration steps; auditors want evidence that controls exist and are checked. Sana prepares a one-page summary for directors, a technical design for engineers, a short guide for the service desk and an evidence register for auditors. Writing one document for everyone would serve none of them well.
5.2 Diagrams
A good identity diagram shows users, the identity provider, applications and the trust relationships between them, with arrows for sign-in flows and labels for protocols such as SAML or OpenID Connect. It omits detail that does not help the reader's decision. Sana dates every diagram and keeps it with the design, so nobody trusts an outdated picture. She draws separate views for staff sign-in, administrator access and account lifecycle, because combining all three in one picture makes each harder to understand.
5.3 Trade-off tables
Choices such as which authenticator to use for depot staff involve trade-offs. Sana uses a table with options as rows and criteria as columns: security, cost, usability in the environment, support effort and resilience when a device is lost. Each cell has a short score and evidence. Readers can disagree with a specific cell rather than the whole recommendation, which makes discussions faster and fairer, and the table records why a choice was made for whoever maintains the system later.
5.4 Plain language
Instead of writing that the council will implement federated authentication with phishing-resistant authenticators, Sana writes that staff will sign in once each morning with a security key or their phone, and that fake sign-in pages will no longer be able to steal their access. She defines any necessary technical term at first use. She tests drafts on a colleague outside IT and rewrites anything they misread, because directors who misunderstand a design may refuse to fund it, however good it is.
Worked example
Sana produces four documents from one design: a one-page director summary, a technical design, a service desk guide and an auditor evidence register.
Synthetic case. Documents and readers are synthetic.
Errors and limits
Writing one long technical document for all audiences leaves directors confused and auditors without evidence.
Exercises
- EX013 — Four documents. Name Sana's four documents. Rubric: 3 = director summary, technical design, desk guide, evidence register;; 2 = three;; 1 = one;; 0 = none.
- EX014 — Separate views. Which three diagram views does Sana draw? Rubric: 3 = staff sign-in, administrator access, account lifecycle;; 2 = two;; 1 = one;; 0 = none.
- EX015 — Plain rewrite. How does Sana test plain-language drafts? Rubric: 3 = ask a colleague outside IT and rewrite misread parts;; 2 = test reader;; 1 = spellcheck;; 0 = none.
Synthesis
Tailored documents, focused diagrams, trade-off tables and plain language get identity designs understood and approved.
Continue studying — chapter 05 of 50
← Chapter 04 (draft) · Course chapter index · Chapter 06 (draft) →