Say It the Way You'd Tell a Friend
Rewriting a cybersecurity game so someone who has never heard of a port can follow every line, without making the security wrong.
Say what it does, not what it's called.
I spent three and a half years at Tetrate turning service-mesh documentation into something people could actually read. Then I wrote a game about cybersecurity and filled it with words like packet, purge, hop count and SIGKILL.
My own note to myself, in September, was blunt: the story and the jargon are too technical, drop it down a notch so common people can follow it.
So I rewrote every line a player sees. The security is the same. The words are not.
The rules I wrote down
Say what it does, not what it’s called. “Messages on the cable”, not “packets”. “Clean it out”, not “purge”. “A trap”, not “a dead-man switch”. A name is a label you have to have learned already. A description works the first time.
Places get names people can say. Every building has a plain label: the centre relay, Juno’s house. Its address still sits underneath in small print, because reading addresses is part of the game. It’s just never the headline.
Numbers only when they help. “3 moves a turn” helps. “You have two fences” helps. Port numbers and uptimes don’t. If the fact matters, say it as a person would: “it has been running for 812 days.”
Keep the words that carry the world. Threats are still ransomware, worm, cryptominer, spyware, because people have heard those words and they’re accurate. The game’s own vocabulary stays too: runner, lurker, island, fence. Each one has a page in the in-game wiki.
People talk like people. Residents type in lowercase. They can be vague, or wrong. That isn’t a writing slip; that’s the testimony mechanic.
The trick I like most
Every action in the game’s log is written twice. The plain sentence comes first. The real command comes after it, dimmed:
› fence the centre relay $ iptables -I INPUT -j DROP # relay-core
› listen in: poppy tower ⇄ the guestbook $ tcpdump -i poppy-guestbookThe plain half is what you need to play. The real half is flavour, and a quiet lesson for anyone who leans in. Nobody is asked to learn it. Some people will anyway, which is the whole point.
How I keep myself honest
There’s a test in the game’s test suite that fails if the case text or the wiki slips back into the banned words. It sounds petty. It’s also the only thing that stops “purge” creeping back in, because “purge” is shorter to type than “clean it out”.
The design documents keep their jargon. They’re for me. The player isn’t me, and that’s the lesson I apparently needed to learn twice.
Seedling. The full vocabulary table lives in the game’s docs; this is the short version.