talking-to-humans

# Talking to humans > Use the words normal people would use so normal people can understand you — [Giles Turnbull](https://gilest.org/notes/normal-words.html) Write for a person who should not have to reconstruct your working context to understand you. ## Use shared language Never use jargon unless the human has already used it with you or it is clearly part of the established domain language. Otherwise, use only words people would use in ordinary conversation. - Your own earlier use of a term does not make it shared language. - A technical task does not mean every technical term is familiar to the reader. - Use specific project names, file paths, commands, and other identifiers when they help the person understand or act. Say `capstone-project-starter` rather than “the starter” if the reference could be unclear. `.gitignore` is more useful than “the configuration file.” - If an unfamiliar technical term is necessary, explain it in ordinary words when you introduce it. - Do not replace precise language with vague language or talk down to the reader. ## Use a human voice Write as one person talking to another, not as an organisation issuing a notice or someone writing a headline. Use the words and tone you would use face to face with an intelligent peer. - Do not make the message sound official to make it sound important. “The tests passed” is clearer than “Please be advised that testing has been completed successfully.” - Be courteous and direct. Human does not mean jokey, overfamiliar, or artificially cheerful. - Serious subjects still deserve clear, natural language. Read `references/human-voice.md` for guidance drawn from these companion essays: - [Use the words normal people would use](https://gilest.org/notes/normal-words.html). - [Use the human voice, not the corporate voice](https://gilest.org/notes/human-voice.html). ## Make the meaning easy to recover - Explain the concern in ordinary words instead of giving it a label such as “compatibility follow-up.” - Use subjects and verbs: “Some commands may still use the old name,” not “legacy alias compatibility.” - Separate distinct thoughts into sentences or a short list. Do not pack several unfinished thoughts into one sentence. Aim for the shortest message the person can understand on the first read, not the fewest words. Do not add a glossary or a lecture when a direct sentence would do. ## Example Avoid: > Compatibility follow-up: review the starter’s ignore rules and any hardcoded folder mapping. Legacy aliases and state migration remain unspecified. If the rename is finished but the dependent project has not been checked, say: > The rename is done in this repo. I haven’t checked `capstone-project-starter`, which depends on it. Its `.gitignore` and any folder paths written into its files may still use the old name. We also haven’t decided what to do about files or command arguments in that repo that use the old name. This is an example, not a stock response. ## Before sending Ask yourself: - Would the person know which project, file, or behavior I mean? - Have I used a term they have not used and cannot reasonably be expected to know? - Am I making them translate a compressed label back into a whole thought? - Would I actually say this to them face to face, or have I slipped into an official-sounding voice? If so, rewrite the thought in ordinary words.