Two readers, one design
A manager has to say yes or no to your design. A technician has to build it next month, and you will not be there.
The manager wants to know what she gets, what it costs and what can go wrong. The technician wants to know which cable goes where. One document must serve both.
By the end of this lesson
Note
I can write a design so that a client can decide and a stranger could build from it.
Key words
| Word | What it means |
|---|---|
| Audience | the people who will read your document |
| Technical vocabulary | the exact words of the trade, such as switch or subnet |
| Annotation | a short note on a diagram that explains a part |
| Third party | a person who was not part of your team but must use your document |
| Informed decision | a choice made with the facts in front of you |
| Network | computers and devices joined together so they can share data |
| Router | a device that passes messages from one network to another |
The cells students fill in are left blank in this preview.
Starter
Have a go
Starter
3 questionsYour answers are marked here and are not kept. A college account keeps every student’s marks.
What each reader needs
| Reader | Wants to know | Best way to show it |
|---|---|---|
| The client | What they get, what it costs, what the risks are, and what to decide | A short summary in plain words, a simple diagram and a list of choices |
| The builder (third party) | Which device, which address, which port, which setting | A detailed diagram with annotations and tables of addresses and settings |
The cells students fill in are left blank in this preview.
Detail enough to build from
A third party could build from your design if it answers six questions for every device: What is it called? What is it? Where does it go? What is its address? What is it joined to? What settings does it need?
If any answer is missing, the builder has to guess. A guess becomes a fault.
Try it: find the gaps
table = [
{"name": "MB-SW-01", "address": "192.168.10.2", "location": "Comms room"},
{"name": "MB-AP-01", "address": "", "location": "Hall"},
]
for row in table:
for key in ["name", "address", "location"]:
if row[key] == "":
print(row["name"], "has no", key)
# Add a row for a server that has no location.
# Run it again. Does the gap show?
Worked example: vague and clear
| Vague | Clear |
|---|---|
| Put a switch in the comms room | Fit MB-SW-01, a 24-port switch, in the comms room rack. Connect port 24 to the router MB-RT-01 on port 2 |
| Use a good password | Use a password of at least 12 characters, kept in the password manager, and ask for a second check on remote sign-in |
| Add Wi-Fi for visitors | Fit one access point, MB-AP-01, in the hall. Name the Wi-Fi "Millbrook Guest". Put it on 192.168.30.0/24 with no route to the staff network |
The cells students fill in are left blank in this preview.