Writing gives you the illusion of control, and then you realize it's just an illusion, that people are going to bring their own stuff into it.
- David SedarisTechnical writing is a strange breed. When you write fiction or poetry or a screenplay, it's a release, it's a way of expressing what is inside yourself, and allowing your imagination to creep into the those little crevices in your brain, and poke about to see what squirms. Writing technical documentation is almost entirely the opposite. It's about getting into the heads of your readers, finding out what makes them tick, how they work, and then presenting them with the information in a way that will make them go "Aha!". It's about taking source documentation that would make your eyelashes curl, and crafting it - shaping it, massaging it, chewing it up and spitting it out - into something that not only makes sense, but is useful, intuitive, and - dare I say it - beautiful.
Beautiful technical documentation? Why yes. I think so. Bad technical writing is hard to use, hard to understand, and hard to find what you want. Good technical documentation is intuitive, easy to navigate, and aesthetically pleasing. Good technical documentation is beautiful.
The question, then, is how to create beautiful technical documentation, and how to know when that's what you've got. While it would seem easy to tell when you
haven't got it, it is not always as simple as it might sound. The problem is the same as a lot of artists and craftsmen complain of - getting too close to the subject matter. One of the reasons that engineers can not generally create effective documentation is because they get too close to the nuts and bolts of the thing. They spend too much time looking at the engine of the beast, that they become unable to describe what colour the paintjob is. That is where the documentation team step in - we bring fresh eyes to the project, and are able to look at it from the top down. We can describe what it looks like, what it does, and how to do it, without having to explain how that happens. But once you've been working on that single document for months, you've been through revisions, and revisions of revisions, you've been bombarded with information from the technical team, you've had requests for more detail, more depth, and more minutiae ... then how do you tell if it is any good? Your advantage - your fresh pair of eyes, your ability to see the big picture, and your talent for information organisation - is no longer whole. Now
you are the one who is too close to the project.
A writer of fiction would tell you this: put the book down, step away from the desk. Leave it for a week or two, a month or two. And then tackle it with fresh eyes. A technical writer would scoff - who has time for all that? This book needs to be released next Wednesday!
Often, the solution is to hand it to someone else - a fellow writer - for review and comment. But what about when that option isn't available either? Every writer has their own method of handling this. What I do is this: I put it down, not for long, but for an afternoon, or overnight. And I write something else. Something completely different. A blog post, for example, or a chapter of a novel, or a short story. Anything that has absolutely nothing in common with the piece you're working on. Ensure the voice that you are writing in changes, the topic changes, the emotion changes. Then, make yourself a cup of tea, and pick the book back up again. But don't start at the beginning. Read it backwards. Read each page, on its own, in reverse order. I even read the paragraphs in reverse order. Start at the last one, and work your way back to the beginning of the book. You're checking for typos, for sentence structure, for punctuation, grammar, and all that good stuff. By reading it out of order, you're less likely to drift off and start thinking about something else. You're more likely to read what's there, rather than what you think is there.
Then find a blank piece of paper. Put yourself in the mind of your customer: What do they need to know? What are they trying to achieve? Why do they have your book? The answers will be myriad - but list the obvious ones out. You need to think about what your customer knows, and what your customer doesn't know - that gap is where your book fits.
Once you're thinking like a customer, pin that list up somewhere you can see it, go back again, and read the book in order. If you're able, read it aloud, it helps to catch odd phrasing. This time, you need to be looking for flow. Make sure each paragraph flows into the next, that each section flows into the next, that each chapter flows into the next. Check that you're introducing concepts in order from the top down - start with the big things, and then explain the detail as you go on. Cut out anything that doesn't fit. Don't be afraid to cut and paste paragraphs, to taste-test them in a new arrangement.
And the whole time - there's only one thing you should be thinking about - your customer. If the customer perceives value in your documentation, if your book bridges that gap between what the customer knows, and what they need to know - then they will see the beauty in it.
Cross-posted from Foss Docs
