Below are my notes and highlights from this session at Write The Docs Europe 2016 in Prague. This is part of a series I wrote during the conference. This is not meant to be transcriptions and may have missed points made during they talk. They solely reflect my interpretations of the talk.
What Writing Fiction Teaches You About Writing Documentation
Three of the four best sellers last year in the US were fiction books. The fourth, and the best seller, was actually non-fiction. But it was written with story telling elements. People are enjoying reading about how Marie Kondo says you should clean your house.
Understand Your Audience
Audience and emotion are key and we as a profession are getting better about it. John Steinbeck has suggested that you should imagine your audience as a specific reader, one person you can focus on and write for.
Consider writing the same piece of documentation for two different reader contexts. In fiction it is common to write a scene from multiple perspectives, especially if it helps move the story along. Writing for different audiences with the same story can be very effective.
Write What You Know
Virginia Woolf said it better as “every secret of a writer’s soul, every experience of his life, every quality of his mind, is written large in his works.”
Be careful to not make assumptions about your audience. Your experiences and expertise will shine through in the docs. But, you can accidentally make assumptions, like “python coders all know how to use a command line.” This isn’t true. So think through the way these experiences and opinions are reflected in the docs. Thursday tends to looks for certain words while editing to identify areas where she may have found a writers opinion instead of what readers need to know.
Be Brief
Charles Dickens was paid by the word. Don’t be Dickens.
Emotion Matters
Instruction manuals are known for the emotion, typically anger, that they impart. Fiction writers want you to feel extreme emotions. As documentations writers we have different options. We can hope to achieve emotions of inspiration and satisfaction. Fiction authors use rising and falling and action to control emotions. If you examine something like Dickens’, A Chrismas Carol, the action rises to the ghosts and then fall so Scrooge can prove he has changed.
Documentation on the other hand is often a cliff. We finish a procedure and leave the user with no climax. No next step.
Kill Your Darlings
We are good writers and love our phrases and words. Those are probably the bits that need to leave. Our readers don’t appreciate overly clever writing. Thursday’s Journalism Professor was careful to remind her that this is what poetry is for.
Provide Context
High levels of complexity can cause confusion and people will assume that things not mentioned are unimportant or old. This is like the assumption that characters in Game of Thrones are assumed to be dead. HBO has worked on providing context for the skipping around that can occur by changing the map at the beginning of the show to show what areas will feature scenes.
We have an advantage over fiction writers here because we can link and cross-reference without worry. Our readers will follow the ones that they need. Fiction writers can only make a reader flip to the glossary so many times.
Reading Orders
How do you tell your readers the order in which to read your documentation? For fiction people argue about the reading order of series, even a two book series. So provide guidance, but listen to your readers. Is your path logical? Are people landing in the middle?
Maintain the Canon
What is the single truth about the product? What is the material that is going to be maintained as the only truth about the product. This canon must be maintained and reissued as needed.
Encourage Fan Fiction
Fans can write anything they want about fiction but it is all centered around a core central truth in the story. If you are writing docs, you want people to write tutorials, plugins, etc. You want an active community. How can we make this easier?
- Create core canon docs.
- Create style guides.
- Offer feedback.
Use Beta Readers and Workshops
Workshops are where readers will review beta versions and provide feedback. It is isn’t editing. It is readers reading and commenting.
Let’s increase our beta docs and get this feedback. Let’s workshop our docs!
Reading and Writing are Connected Habits
The more widely read you are, the better your writing will be. It is important to keep doing both.
