Last time we talked about some of the things that marketers do to hide the warts in their products.  A lot of people commented on this post, apparently I struck a nerve.  Here are some of my favorite comments:

“You make marketers look like liars.”

“OMG I remember doing this exact thing, did we work together?”

“WHY ARE YOU GIVING AWAY ALL OF THESE TRADE SECRETS?”

Just to be clear, I didn’t call all marketers liars, I just pointed out that there is indeed a point when messaging becomes disingenuous.  The marketer owes it to the reader to present material factually and clearly, and perhaps in some circumstances they didn’t do a good job of that.  Maybe they left out an important data point, maybe they selectively used the best data, maybe the way they described something wasn’t very clear. 

Let’s dive right in and talk about how to make your technical marketing amazing!

Making amazing content

Marketing materials run the gamut from catchphrases to product documentation (that’s right, documentation is marketing).  Each level of marketing deserves it’s own set of rules and adherence to facts.  So catchphrases can be bizarre and provocative but documentation should be factual and accurate.

Technical marketing should be:

• Concise
• Free from hyperbole
• Technically accurate
• Rooted in the present or near future
• Leave you wanting more information, but not confused
• Make you feel like you are not wasting your time
• And most importantly, trustworthy!

So how do Technical Marketing Engineers (TMEs) achieve this?  It’s actually quite difficult!  As you read that list you probably realized that some items conflict with others.  There’s a lot of room for nuance.  You don’t want to withhold information, but you can’t exactly include release note information in an architectural slide deck.  Each technical asset should be focused on a different point in the customer’s journey, and there is a right time for everything.

Know the audience

Each asset, from an introductory slide deck to a set of release notes, is targeted at a certain level of reader.  These are sometimes considered marketing personas, but it is important to differentiate between actual personas and seniority levels.  To understand how differenced the language and presentation style can be between different types of documents, it helps to take a single product (take a firewall for example) and review the intro slide deck, the technical decision maker deck, the solution architecture whitepaper, and the end user documentation.  Each of these will be written in a different style and will likely contain different levels of abstraction on the topic. Each asset should build on the previous telling of the story. The viewer goes down the rabbit hole.

Write like a human, but not like a slob

Technical documents can be overly dense, and it is important to not lose the reader.  You don’t want the asset you’re creating to sound like a machine wrote it, and you don’t want it to sound like your uncle who has had one too many egg nogs.  In general, you want to avoid using personal pronouns.  For example, “we”, “you”, “us” should be avoided if possible.  Admittedly, the word “you” is hard to eliminate from documentation, but it should be used sparingly.  There are a few exceptions to this rule, such as the easter egg example below.

Vary your writing style

Some people insist on writing everything in the active voice, but I find that mixing between active and passive voices makes the content much more interesting and easier to read.  This is at your own discretion, some documents may require only the active voice.

But be consistent when it comes to data

Make sure all your units, technical terms and phrases are consistent.  For example, leaf-spine and spine-leaf and leaf/spine are all different phrases.  They likely mean the same thing, but it makes the reader do mental gymnastics if you are constantly mixing things up.  Use the same types of abbreviations, so Layer-2 and Layer-3, not Layer-2 and Layer 3.  Introduce acronyms before using them, so write Layer-2 (L2) and then you can use L2 to simplify the writing later on in the document.  Don’t assume that your audience knows every term you are going to throw at them.  Make sure the terms are absolutely accurate, for example it is written “Clos” not CLOS (it’s a last name, not an acronym!).  These little details make a huge difference in showing your reader that you know the topic very well. 

Also, you need to adhere to the weird tribal knowledge in your particular area. For example, in the data center switch fabric design, we talk about LEAFS not LEAVES. It’s not grammatically correct but it is the correct usage in this audience.

“Well how should I know all of these things?”  YOU ARE THE EXPERT.  YOU MAKE THE BIG BUCKS.  You should know every word or phrase you write.

Avoid idioms

Idioms and other sentence structures are so much fun to use, but they are not well understood by foreign readers, and they’re often ageist, so the younger generation will not get the full meaning.  This isn’t a hard and fast rule, but just be aware of how your text may appear to others.

Use images and graphics

These days people have very short attention spans, you need to break up long sections of text with graphics.  They don’t need to be complex, just simple illustrations of concepts or block diagrams will suffice.  Don’t try to overdo it, less is typically better and you can always add more detail later.  If you are not good at creating diagrams just draw it with a pencil and take a photo of it and include that.  When the document is finalized by your creative them they are responsible for making it look pretty.

Easter Eggs

Part of the challenge of technical marketing is how to keep the audience engaged when dealing with dry or tedious material.  This can be rather difficult.  What generally works best is to add little bits of levity or easter eggs.  This might sound silly at first, but do I need to tell you how awful it is reading technical documents that sound like they were written by some sort of overly-depressed AI?  This is where humans can really differentiate.  Here is a good example I like to use to break up a large set of complex ordered configuration tasks:

That tiny thing does a few things.  It makes it clear to the reader that a human wrote the docs, that they commiserate with the reader on how difficult some tasks may be, and it makes the person feel like they completed a milestone and deserve a reward or break.  This makes the difference between documentation that is a chore to read and something that people want to read because they’re looking for more easter eggs.  It’s a form of gamification.

Use a table of contents

This is actually very useful for a number of reasons.  First off, it ensures that the reader can skim and that they know the approximate length of a presentation or document.  But more importantly, it helps you as the author write content that is well structured and evenly paced.  If you don’t want to include the table of contents in the document, at least write it first with the TOC and then remove it when you are done.  It will help keep you on track.  I typically write the TOC first and then go to each section and write it individually, so each section stands on its own.

Do brain dumps

You can never have too much source material.  Typically, complex documents are written by multiple authors.  As an example, I will sometimes ask someone to fill in a certain section with their config examples or command outputs.  I like to ask contributors to do brain dumps and not worry about style or organization.  As a document takes shape, I move unnecessary bits of information to the end of the document into a “Extra” section.  Who knows if you’ll need to reference it at some point.  When the document gets finalized, simply cut out the extra section.

Always look to simplify

Read your materials and look for complex sentences.  Try and find pieces of text that don’t add anything to the document.  Look for superfluous words.  Be utterly ruthless in your editing, but make sure you are not breaking the message by removing important pieces.

Review, Review, Review

I am never 100% happy with most of my creations.  There’s always room for improvement and the more I read it (and recite it out loud) the more those needed enhancements will appear.  Even when delivering a highly rehearsed and recorded live presentation, I always notice something new in my slides or materials that could be tightened up. Read things again at different times of day, you’ll start to notice things that you didn’t pick up the first few times.

Always summarize in a conclusion

This is obvious when writing an essay, but it is good form for slide decks, recorded presentations, white papers, everything really. Find a nice way to wrap it all together

I hope that this post was useful for my peers as they work to evangelize the latest and greatest technology in IT. 

Now it is time for that iced coffee!

---

“ssh-keygen -b 2048 -t rsa”

— Homer