| Authors: | Daniya Kamran |
|---|---|
| Time: | 9:40 |
| Session: | http://docs.writethedocs.org/en/2013/conference/talks.html#daniya-kamran |
| Link: | @daniyakamran |
Kamran is an interventionist and a translator: her job is to take complex, deep topics like nutrition for children or the state of higher education, and turn them into something that’s accessible and comprehensible. This is an intervention: words intervene in the reader’s train of thought, and have the ability to redirect the course of their thoughts. That’s a pretty decent responsibility.
Immortality Poetry is very good at immortality. When you write you can not write thinking that your writing will never be seen again. We know that the technology we write about will someday be obsolete and irrelevant. You may think that this knowledge doesn’t come across in our writing, but it does. The reader can tell that you’re only writing it well enough to survive for 18 months. Poets write to transcend time: they don’t believe that context is required to understand and appreciate the work. Who today understands the full context of Shakespeare? Good writing will get replaced at some point. Bad writing will be replaced immediately. Epic writing will be edited. Your writing can and will remain if you’re writing well. Write to be immortal.
Dilemma We assume that when people read documentation, they know why they’re reading them. That’s not always the case; it’s not even clear that it’s usually the case. Poets are very good at dilemma and making them apparent. [Frost, “The Road Not Taken”, 1920] Your worst enemy as a documentarian is not someone else’s document or book or whatever, it’s a lack of initiative. Making a dissonance obvious creates a sense of urgency, increases the readers’ feeling of autonomy, and provides the call to action that your user needs to move forward. If your document creates this dilemma, your reader will want to continue reading.
Bias Be biased: there is such a thing as a point of view. Scientists are allergic to a point of view, the value objectivity. “You don’t have a point of view, but you can tell me fifteen others? You must be smart.” But your reader comes to your documentation because they want your expertise: they want to benefit from the work you’ve done. They’re coming to you because you’re an expert. Wordsworth accuses the reader of being dull if they can’t appreciate London in “Composed Upon Westminster Bridge” (1802). That’s a bias! Expertise requires a point of view. A point of view provides context.
Error Poetry is all about errors: bad things happen all the time. Ships sink, people eat each other, everything goes to hell, and it’s awful. But it makes for really good poetry, and most of the time we don’t wind up hating the author. Why is poetry still epic even when everything is going wrong? Because it deals with a cyclical journey. As engineers or scientists, we think of error as a consequence, not as part of a natural cycle. Being OK with breaking things is how great computer scientists are born: they’re OK with breaking things, and come up with better ways to fix them. Do not consider error punctuation: it’s part of the process. We’re good at recognizing the temporary nature of what we do, but we should also recognize it as provisional: it will be edited.
Reiteration Poetry is great at using reiteration and repetition to reinforce what’s important. [Shel Silverstein, “Where the Sidewalk Ends”, 1974] After every complexity, reiterating the purpose makes the purpose palatable, digestible, and keeps the purpose at the forefront of the reader’s mind. Iteration ensures that the readers doesn’t lose sight of why they’re reading.
Metaphors All of the words we can use, the evidence we can draw from to write documentation; it already exists. What we do as documentarians is arrange them in new and interesting ways, constructing new metaphors that illuminate the ideas for new readers. The beauty of writing is its ability to draw from different sources and refer to different contexts. Metaphors let the reader bring something from themselves into the reading. That keeps them engaged in the document.
As Scribes we have an immense responsibility: the responsibility to create an intervention in how people do something. The way we can learn to do this is by reading the masters. And in reading the masters, we’re going to be better at communicating complex concepts to others. If you can make your documents elegant, you can translate science and complexity into poetry. Elegance is poetry’s punchline.