Lightning in the Garden
The right word in the right place
This blog post is part of the Trailhead content creator series. Follow The Trailblazer publication to read the entire series.
If you haven’t noticed, we talk a lot about Lightning in Salesforce. I figured starting off this post with a quote that talks about writing and lightning would be pure gold. And thanks to the interwebs, we have a winner.
The difference between the right word and the nearly right word is the same as the difference between lightning and the lightning bug.
That quote was penned by none other than Mark Twain. Or maybe Abraham Lincoln. Or the Dalai Lama. Oscar Wilde? One of them for sure.
Based on the amazing success that Trailhead has had since its inception, it’s obvious that we’ve generated a lot of lightning and weeded out lots of lightning bugs. Finding the right words is rarely an easy feat, but the task is made vastly easier by the series of editing checks and balances the Trailhead and technical writing teams have in place.
What does our editing methodology entail? To help illustrate this, I’m stealing some terminology from gardening, and specifically, pruning.
What exactly is pruning, anyway? The cutting away of dead and overgrown branches and stems to increase growth and fruitfulness. If there’s a better analogy for editing, I know not what it is.
Let’s break down how editing works here with Team Trailhead.
P
Prepare the outline.
The writer’s outline is the first major output that is closely edited by a member of the Trailhead editing team. Editors have to answer a series of questions to make sure the content hits the right notes.
Does it meet our customers’ needs? Does it fit in with the Trailhead vision? Does it communicate the vision of the product managers and how they see their product used in the market?
If the answer to any of these questions is negative, back to the drawing board we go for a new outline. Obviously, there’s a brief period of devastation caused by a content editor’s rejection of a carefully crafted piece of work. Devastation is soon followed by a new flurry of work to compose a new outline that meets the high Trailhead standards.
When the outline is finally approved, the writer tackles the actual writing of the content.
R
Review the first unit.
After the outline, the first bit of prose up for review is the very first unit the writer completes. First impressions are everything, and the first unit of a module is that content’s first impression to the world. The Trailhead editors make sure it’s striking the right tone and setting the correct pace for the rest of the module. They separate the lightning from the lightning bugs, so to speak.
With the all-clear from the editing team, writers can proceed with subsequent units, confident that their content is off to a good start.
U
Unite stakeholders for editing.
After approving the outline and looking at the first unit, Trailhead editors have a pretty good idea of what your content is about. However, writers still need a variety of other eyes on the content before it goes live.
Getting buy-in from subject matter experts is key in releasing quality content.
Depending on the subject and audience, these experts can be anywhere from product managers, marketing folks, fellow writers, and even customers — or any combination from that list.
Each stakeholder brings a unique perspective to the content, which in turn makes it technically accurate and relevant.
N
Nothing left to chance.
By now you’re thinking, well, that’s enough eyes on your content, right? But we never want to leave anything to chance. Once the content has been through content editing, it goes through a copy editor who makes sure your and you’re and its and it’s are all where they’re supposed to be.
And let’s not forget the testing! I know everyone thinks our fabulous quizzes and hands-on challenges spring from the ground fully formed. But really, from inception to their release, they go through a bunch of testing to make sure that they actually work.
E
Enjoy your module.
At this point, writers have seen their content change, mature, and (dare I say it?) blossom. There’s nothing left for writers to do but sit back, open some bubbly, and enjoy the accolades as they pour in.
Or watch nervously as their content hits the big time, and fret about having a typo make it through all those checks and balances anyway.
You know, the daily life of a lightning seeker.
Mersedeh is a senior technical writer, with a focus on Community Cloud. In a former life, she was an architectural conservator.
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.
