When Wishing Still Helped … What Folklore Can Teach Us about Technical Writing


A great while ago, when the world was full of wonders, technical writers just described the systems that we were documenting. Sometimes, we got adventurous and wrote laundry lists of procedures. These early practices led to the phrase RTFM (Read the F____ Manual), because NO ONE ever didl, even if the answer was there. We didn’t think much about what our customers wanted or the user stories that they live by.

But any folklorist or linguist can tell you that narrative is the basic structure of reality--whether those stories are fairy tales, Biblical parables, or the instructions that teach a systems administrator how to install a virtual machine.

In the 1800s folktale collectors tramped across Europe, Asia, and the United States recording the stories that people told around the fire and in their homes. These early folklorists quickly discovered that these stories follow set structures and have archetypal characters.

Technical documentation also has fixed structures and archetypal characters. But instead of talking about scullery maids and third sons, technical writers compose stories where the heroes are customers, developers, and systems administrators.

The Russian folklorist Vladimir Propp decomposed all of Russian folktales into 31 “narratemes” or story elements. Similarly at Red Hat, we divided all of our documentation into two role-based life cycles: one for developers and one for administrators, with fixed tasks for each role. Sure, there are still a few tasks and concepts that can fall outside these standard structures, just like there are some fairy tales that are unique. But the vast majority of our user stories and epics fit within these narratemes.

In this talk I’ll introduce the audience to tale types and folktale motifs and show how similar these are to Red Hat’s standard life-cycle components. I’ll show diagrams that content strategists created at Red Hat to show product life cycles and real examples of content that fits within these standard categories. I’ll help you listen and find the story of the people for whom you’re writing.

So that we may all live happily ever after.

  • Conference: Write the Docs Prague
  • Year: 2020

About the speaker

Ingrid K Towey