Say, it’s only a paper moon,
Sailing over a cardboard sea,
But it wouldn’t be make believe,
If you believed in me.
-Billy Rose, recorded by Ella Fitzgerald, 1938
A Tech Writer Talks Make Believe — and Keeping the Windows Closed
One of my best writing teachers told me to use allegory whenever possible. Draw inferences. Try something new. She used to say: “Use all the tools in your writer’s toolbox, when you can, not just the obvious ones, to get across a concept.” Writing that has thought behind it has a different feel. What makes it so good? And what does this has to do with Post It Note butterflies? Read on.
Go Where Your People Live
Like a good novel, you have to reach your audience where they live. Technical writing, at its best, is personal training, one-on-one, for someone you will never meet or know. When I am thinking about the audience, and this someone I will never meet, this someone who will read my manual, I often give him or her a face, a name, and a reading style. Joe, a 45-year-old phone technician, is a fast reader. He has only a high school education, but don’t worry, he knows his work inside out. He skips around the text, uses the index constantly. The manual, if printed, has to lie flat in the front seat of his truck….
Position Available: All Writers Need Apply
I believe a good writer needs to be a generalist. You can argue this one with me if you wish. A good liberal arts education, with evidence of mastery of an academic field (English, science, art history, economics, or what-have-you), and some technical training, on the job, or in class, works for me. An advanced degree, but not necessarily in writing or English is great. You know that person had to write a thesis, and can research a topic well, and write in a formalized structure.
But being a really good problem solver: that is the sign of a well-rounded writer with potential to innovate. It is the best part of human nature to innovate; or where will we all be in twenty years? Still doing the same thing? Saying the same words?
Keep the Windows Open
When I was a tech writer, sitting at a desk all day, plying my trade, I used to have a little window open at the bottom of my screen. No, it wasn’t a stock ticker… or an instant messenger… it was my latest writing piece. Often it was a poem that popped into my head on the drive to work. One day, a screenplay showed up. Sometimes it was just an email I was trying to write to compose well.
Remember, writing is writing is writing and you have to stick to it to be good. Eight hours of tech writing, day after day, with a little prose thrown in, can get you there over time. Like learning how to ski, you just have to go up on that lift over and over and over. Log your hours. Get tired. Get up and do it again.
Faulkner or Hemingway? or Maybe a Little Sartre?
Another trick I use is to keep a good book on my desk at work to inspire me. They say to learn how to write, copy the good writers. I am partial to certain past writers and poets (William Carlos Williams and that little red wheelbarrow — and Dylan Thomas’ A Child’s Christmas in Wales — all those yummy Welsh pies and treats) but I also like current writers like Jamaica Kincaid. Her run-on style is all over the map, yet she still keeps you “in the loop” somehow. How does she do it?
If you are not literary, this can help you. I am a NY Times crossword buff. Sometimes I wander into the acrostics and such, but they usually stump me. Puzzles can keep your mind nimble on days when you cannot write another step.
Writer’s Block Is for the Idle Rich
When I started out as a tech writer, the blank page really frightened me. Better fill it up, I thought. Can’t have the boss walk by and see me staring into space. Now, I am more relaxed — I have met so many deadlines, I don’t feel I have to start before I’m ready. They say in tech writing school, take notes, but I don’t take notes anymore, like I used to. I listen. I listen a lot. I found that if I took notes, I wasn’t listening, I was recording, and that is NOT the same thing. Now I just hunker down and watch.
I watch the screen and I watch the programmer’s face as she tells me the “story” of her “creation.” Meanwhile, I am thinking: how to get this across? I’m thinking: bias. What is the technological bias — did the programmer use the latest gadgets or the ones that really work?
Where’s the Catch?
I’m also thinking: how does it work? Is it screen-heavy? How’s the navigation? Can I skip UI description altogether (I hope) or is something counter-intuitive? Is the structure (logic) still showing, like an exposed dinosaur bone in the sun, or is it far more elegant (or confusing)? Where’s the catch? Is there a problem here that needs explaining (or explaining away)? Everything made by a human leaves a human mark. How do I get around it?
Writer’s block is for novices or people who don’t write for a living. I would love to wander down to the local café, full of angst and coffee, and wait for “inspiration.” I don’t have time! All you have to do is write on deadline for a few months, and that blank page that scared you so much won’t be blank for long.
Little Yellow Butterflies
On my first big contract, notes had become a crutch for me, and I knew it. I thought, if I write it all down, then it is all here when I leave. I’ll figure it out when I get home! Now I know: if I don’t understand something, ASK at all costs. Your notes are meaningless in a few weeks or so…in fact, they are useless right away if they aren’t correct or your handwriting is illegible (like mine). Post It Notes are usually not the answer.
I cured myself one day of taking too many notes instead of actually paying attention, when I was driving down the highway, enjoying the breeze of my open car window. I noticed a lot of little yellow butterflies in my rear-view mirror. Maybe fifty!
Wait, those weren’t butterflies! Those were my notes! All my little yellow Post It Notes had “flown” out the window, like little origami butterflies! And the docs were due in a month. How was I going to interview those twenty programmers all over again — they were too busy to talk to me!
Well, I decided right then and there, only write down what matters. The rest can fly away. Just let it go, the details, the trivia, the endless amounts of Post It Notes. And use the air conditioning. OK, so maybe you don’t want to keep ALL your windows open. Just the ones on screen.
Say, It’s Only a Paper Moon
Of course, even I know tech writing is not creative writing, but…. the highest compliment I ever got about my technical writing was from an employer who told me “your online help reads like poetry: succinct, clean, concrete, but with punch…”
Always keep in mind this song and even your most technical writing will stay fresh:
Say, it’s only a paper moon,
Sailing over a cardboard sea,
But it wouldn’t be make believe,
If you believed in me.
Believe in Yourself and Your Writing
You have to believe in yourself as a writer before someone else will believe in you, too. And that is where the magic begins. Remember, Amy Tan worked at IBM. And look how far she got after that.
© 2022 CafeFAQ
Credits: Origami Boat by Alex Padurariu . Open Window by Katerina Pavlyuchkova . Butterflies by __ drz __ . Moon by NASA
Originally published at https://cafefaq.com on July 15, 2022.
