I’m at Write the Docs today in Portland and will be posting notes from sessions throughout the day. These are all posted right after a talk finishes so they’re rough around the edges.
Daniya started by stating that she is not strictly a documentarian. She’s a translator and interventionist. She turns crazy black hole-style concepts in to simplistic solutions. She focuses on questions like, “How do we turn around how people view nutrition?”
Documentation is an intervention. You’re creating an intervention from the perspective of the user. It changes the way they relate to a product and their train of thought when using the product.
The techniques and processes she presented are not a checklist. They’re strategies you can employ selectively to reach your goal. Her goal is to give you a poetic lens for your work. If you don’t like poetry, scientific documents, or want her to just show you how to write the docs then you’re not going to like this.
Poetry is very good at immortality. When you write you cannot write thinking that what you’re writing is never going to be seen again. If we assume documents are temporary it will come across in our writing. The user can tell. Poets write to transcend time. As programmers and as documentarians we don’t do this. Even if no one understands your work they should at least know that you wrote it. Write thinking that you’re a bad ass. Here’s Daniya’s guideline: Good writing will get replaced. Bad writing will get replaced immediately. Epic writing will be edited. Be epic.
Poetry is always about a dilemma. There’s something about to happen that you can’t quite figure out and need to solve. We assume that people know why they are reading the docs. There needs to be a context for what is being created. Docs, ultimately, answer the question, “What do I do?” In many, many docs this is not obvious. Your worst enemy is not a competing document; but a lack of initiative. Someone is going to read what you wrote and nothing will happen. In making dissonance obvious we create a sense of urgency, increase user autonomy, and provide a call to action.
Daniya says we should be biased. There is such a thing as a point of view. Scientists are very allergic to a point of view; they don’t like it at all. We associate objectivity with intelligence, even though that’s not always the case. The person reading your docs is coming to you because you’re the expert. They don’t want to do the thinking that you did. They want the answer. There’s a reason opinions flow and have an impact. A lot of it just has to do with assuming you are the expert and writing accordingly. Influence your readers. The goal is to be holistic. Encase your opinion in objective analyses as well as other opinions. Having the point of view provides the reader context. They can understand that you’re human.
Another thing scientists are allergic to is error. Poetry deals with it in a fascinating way. In some ways poetry is all about error; bad things happen all the time. As Daniya said, “Why is epic poetry still epic when everything is going wrong?” Poetry deals with things as part of a cyclical process. When you view things as part of a process it removes a large aspect of the negativity. Daniya also phrased it as, “a lack of error is very contrary to human ability.” An error is not a consequence, it is amendment to the process and a part of the process. It’s temporary and provisional and will, eventually, be edited and improved.
Poetry is very, very good at reiteration. What reiteration allows is for us to remember the purpose after every major turning point and complexity. People should not forget why they are reading what they are reading. Reiteration allows them to connect the current complexity back to the original purpose. Periodically bringing back context allows a reader to never lose sight of what you’re trying to do.
Metaphors are, in some ways, the most important point. All the evidence you’ll be drawing from to write your docs already exists. We merely rearrange bits of information in new and interesting ways. All we are doing is creating metaphors. They allow us to rearrange the patterns of our mind. We’re making remote associations between things we didn’t think were related at all. The reader fills in these patterns and associations and, thus, connects more deeply to your writing. Instead of pushing something out of the page the reader is pulling it out of themselves.
As documentarians we are adding to how people view communication. The way you ensure that your documentation is eternal is to make sure as many people as possible can read it, leverage it, and connect with it. The bottom line in all this is elegance. Can you make your documents elegant? If you can capture this in your words and in to your page then you have done everything you can.