Yesterday I spent 8 hours debugging a broken AI system.
The symptom: searches for “Keytruda” (a rather unique word) returned no results, despite the database containing clear information about this medication.
The cause? A database column named “content” that stored content, configured through a parameter called “Content Column Name.”
My confusion caused the json content to become nested one level too deep into the database.
This naming ambiguity cascaded through the entire system, fragmenting data and breaking search functionality. The fix was embarrassingly simple: rename the column to “inhoud” (Dutch for content).
Easy fix: The Dutch Advantage
Dutch developers have a secret weapon here. We can use Nederlandse termen to eliminate English ambiguity:
- content → inhoud vs configuratie
- data → gegevens vs datatype
- process → verwerken vs proces
The linguistic separation creates conceptual clarity. You can’t accidentally use “inhoud” for configuration settings.
The ASD-STE100 Connection
This reminded me of ASD Simplified Technical English (ASD-STE100) – the aerospace industry’s controlled language standard with a restricted vocabulary of ~900 approved words and strict grammar rules.
I learned to use this to write Maintenance Manuals for the Fokker 100 and 70 in the 90’s. Back then it was still called AecMA Simplified English. It is now maintained by the Aerospace and Defence Industries Association of Europe.
The standard eliminates ambiguity from maintenance manuals through rules like:
- One word = one meaning only
- Maximum 20 words per sentence
- No synonyms (choose “repair” OR “fix”, never both)
- Prohibited constructions that create parsing ambiguity
Native English writers hated it, they said it sounds like Mickey Mouse English. I love it.
Deconfuser ahead:
“Remove the bolt holding the fuel line”
This could mean:
- Remove the bolt that holds the fuel line
- Remove the bolt while you hold the line
Your choice as a writer. Make it matter.
Switch the pump on.
Great, and how am I going to do that?
O wait, you mean:
Set the pump switch in “on” position.
There is an precise list of nouns that you may not use as verbs.
Switch is NOT
– to switch
but
– he device that is a switch.
The Software Parallel
Software faces the same challenge. We use terms like:
- “data” for both information and data types
- “process” for both actions and system processes
- “status” for both states and messages
- “result” for both outcomes and return values
Nederlands to the rescue
I use Dutch words to name variables if I find the English version too confusion. Sometimes I forget and or don’t care or want to make my code look “international” and that is when the crap can start happening.
The Takeaway
Technical communication isn’t just about conveying information – it’s about eliminating every possible misinterpretation.
My AI now works perfectly. All because I choose better words and spotted the nested column.
Sometimes the most advanced fix is the simplest one.