The Descriptivist Manifesto¶
Description
It's easy to assume that the "technical" portion of technical writing is adherence to rules: document specifications, style guides, and the like. But so many of the alleged rules of English come from decades-old myths or the whims of long-dead grammarians. How can we, as documentarians, ensure that the rules we follow reflect excellent contemporary writing, as determined by both the world at large and by our industry-specific language communities?
My answer to this problem is to constantly apply my training as a descriptive linguist to my technical writing practice. I'll show how to apply basic methods of corpus linguistics to quickly answer usage questions, drawing on resources as large as the 200 billion words in the Google Books corpus or as small as a single Figma file shared among a few teammates. These tools can quickly reveal patterns of existing usage, preventing us from imposing unnatural choices on our writing.
Adopting a descriptive view lets us document our products the same way we talk about our products, eliminating a translation step that opens up the risk of introducing factual errors. Ultimately, building linguistic consensus within our teams and addressing our readers in language that feels familiar builds truly communicative documentation, not merely "technical" writing.
- Conference: Write the Docs Portland
- Year: 2023
