It’s What You See, Not What You Know
Technical writing lessons from the art world
This blog post is part of the Trailhead content creator series. Follow The Trailblazer publication to read the entire series.
“Draw what you see, not what you know to be there.”
That’s what a drawing teacher told me some decades ago. I’d been working with words as an editor and writer and decided to learn a little about drawing and painting. So I signed up for a basic drawing adult ed class at the local community center.
At the first class, the teacher put two narrow sticks of wood, each a couple feet long, on the table in the middle of the class. He had us walk around the table and notice that the sticks looked different from different spots in the room. They looked either longer or shorter, seemed to be positioned at different angles. He told us we knew the sticks were the same length and width, but they didn’t look that way depending on where you stood.
Then he said, “Stop where you are and draw what you see, not what you know to be there.”
My lines were timid, and they weren’t even straight. But when I stood back after quickly drawing the sticks a few times, I noticed the angles and lengths were all pretty close to what I’d seen where I stood. And, even better, I had just enough success to keep me going through that class, and (as it turned out) a few more.
The teacher could have started with lots of technical stuff — about the right kinds of instruments for different types of drawing, about how to sharpen and hold pencils, about different kinds of paper, and so on. I learned a lot about that, and more, in other classes about drawing and painting.
But mostly I learned refinements on that first lesson — to focus less on what I was trying to draw and more on just looking.
I learned how to look closely at light and dark. How to see negative space — the space around objects. How to see and measure proportion. Doing art seemed to be more about looking, and a lot less about using your hand and arm the right way or choosing exactly the right color or shade. The more I looked, the more I could see and understand the object I was trying to represent. And the deeper that seeing, the less I thought about what I was doing — my hand trying to apply line and color to paper — and the more I just created.
To go from the sublime to my actual topic, fast forward to early this year while I was writing my first Trailhead module. My manager (I’ll call him “Phil”) and I kept going round and round with one of my drafts. I was writing about how to set up Sales Wave, an app from Salesforce you’d use to do analytics on your Sales Cloud data. You answer the questions in a configuration wizard, click Create, and voila!, Sales Wave gives you a set of dashboards with cool visual representations of your opportunities and accounts.
Using the configuration wizard takes a fair amount of thought and some understanding of both your data and how the app works. Having worked with the development team, I knew a lot about both and I was putting time and effort into explaining the detail.
Planning our trail, Phil and I had decided that the most important thing would be to tell a clear, engaging story. The characters needed to be believable, and they needed to have realistic experiences performing real-world tasks with Salesforce.
The rest of the Sales Wave trail fell into place easily. But the unit on the configuration wizard was tough. I thought we had to explain a lot or we’d be doing our customers a disservice. He thought the explanations slowed down the narrative. We went back and forth until Phil said one afternoon as we reviewed my latest draft, “Maybe you don’t need to tell people everything you know about Sales Wave. Maybe we just need to let people have a little quick success.”
“Maybe you don’t need to tell people everything you know about Sales Wave. Maybe we just need to let people have a little quick success.”
With that guidance, I went back to my desk and thought about the customer’s experience. How could I give them just what they needed, so they could take that knowledge and run with it? How could I help them be successful quickly so they’d want to explore deeper on their own? I ended up going through the wizard a couple of times, the first time accepting all the default answers, the second making just a couple different selections. I took before and after screenshots showing the difference those few selections made to the resulting dashboards. Then I wrote up the process for customers to follow so they could try it out quickly and see for themselves.
And that seemed to do the trick. Phil liked it, and that’s what made it into the Trailhead module you can see today.
That lesson has stayed with me. Later, when writing other Trailhead modules, I’d get stumped trying to explain the technology.
I’d stop myself and think about the reader’s experience — and the customer’s experience using the technology.
Forgetting all the daily scrum meetings, all the product specs, the user stories, the prototypes, and engineering demos of new features. Looking closely at what a person might experience using the software, and what might make it useful and appealing to them. And then writing for that experience.
What had I done? Described the customer’s experience, not what I knew to be in the product. A lot like what that drawing teacher had told me so long ago.
Paul has written stuff for a long time, technical and otherwise. He’s been a proud member of the Salesforce Wave Analytics docs team for the past couple of years.
Interested in learning more? Come to our session at Dreamforce and learn how to write the Trailhead way.
How to Write the Trailhead Way
* Tuesday, October 4; 2:30–2:50pm PT
* Moscone West, Admin Meadow Theater
Can’t make it in-person? The session won’t be streamed, but we’ll be posting the materials afterward on the Success Community in the Trailhead group.
