Here’s how I learned vocabulary. Every day I was given a list of words. For homework I had to define each word and then use it in a sentence.
Defining the word was easy. Just look it up in the dictionary.
Abreast: possessing current information about a subject
Using the word in a sentence was much harder and I would struggle to produce a tortured sentence, like this:
I am abreast of the cafeteria menu, because I ate a corndog and tater tots for lunch.
The preceding usage is crude to the point of naïveté. But it gets worse. With such a shaky grasp on the subject matter, what happens when you encounter the word in the wild, like this: (from King Henry V):
My soul shall thine keep company to heaven; Tarry, sweet soul, for mine, then fly abreast, As in this glorious and well-foughten field We kept together in our chivalry!
WTF. There’s nothing about corndogs in here.
The fact is, if you really want to understand a word’s meaning, you have to see it in different contexts. And as you can see from the preceding examples, the richness of the context drives the richness of your understanding.
Enter the how-to article
No normal person has the intellectual horsepower to keep up with more than one or two facets of the current technology ecosystem.
What that means is that most of us are miserably writing sentences about corndogs when we really want to be crafting sonnets.
How to bridge the gap? That’s the question.
What would be really helpful is to see example usages with rich context. Here’s an example from Google’s Firebase product. Scroll to the end for the breakdown.
Let’s break this sucker down
- Title: This is the hook. The title grabs the reader’s attention and makes them want to read more. A well-written title should entice.
- Feedback: The feedback widget allows the end-user to comment and rate on the content provided in the how-to.
- Overview: This shows the user an overview of the article, so the user knows where she is, what comes next, and how long it will take to reach the conclusion.
- Audience: Who is this article meant for? Does the content match the user’s intent?
- Prerequisites: What do you need to get started? This is similar to the ingredients list in a recipe
- Step 1: At last. We’re down to brass tacks. Note that the author leads with an explanation of why the step is necessary. More context.
- Step 2: Note that the title of each step begins with a verb. Imperative sentences are simpler because you don’t need a pronoun.
- Step 3: Note that this step provides its own micro-context. It’s almost a how-to within a how-to. See items 9-11 below.
- Version Context: Firebase is a mature product with multiple versions. Without version context you could easily go astray.
- Actual code: This is the first time you see actual code! Realize that at this point you have gotten nine layers of context! (I am excluding the feedback widget because it doesn’t directly provide context) Literally everything that came before was meant to provide context around a few lines of code!
- External resources: Links to important external resources begin to nudge the reader to action.
- Next steps: Finally the next steps section puts this specific article into the context of a more holistic learning path.
Here’s a fun thought experiment. If you had to guess, what is the CTA (call to action) of this web page? In other words, what does the Firebase team want the reader to do after reading this article.
Here’s a hint. In the content marketing world, the CTA is so important that it usually appears at the top and the bottom of the page, so that the reader will have multiple opportunities to act.
In this example, the CTA is the feedback widget, which appears at the top and bottom of the page.
What Firebase understands is that having a crappy how-to article in the wild is actually worse than having crappy software in the wild.
To understand why that would be, realize that negligence in writing code only affects your customers. Negligence in writing how-to’s affects potential customers and reduces your total addressable market.
In other words, the flow rate of your delivery pipeline is a function of the flow rate of your teaching pipeline. That’s why Firebase devotes precious screen real estate to solicit feedback about the how-to.
The Meta Context
In my professional life I often encounter resistance to writing documentation. But writing how-to’s is a lot of work! Investment in documentation will drain investment from feature development.
This mindset is common in the SaaS world, where people conflate feature parity with competition.
But in the PaaS world, feature parity is not where the fight is.
Check out this screen grab.
One reason that your documentation and developer portal are so important for PaaS companies is because they provide more stuff for the search engines to index. That means the search engines can match your platform documentation with the appropriate search intent, which gives you a huge advantage over the competition.
In essence, developer documentation and content marketing have become tightly overlapping constructs. That’s where the fight is.
I'm hiring software engineers! Check out the jobs page to see my open positions.