Technical Writing for Learners vs Builders

Before putting finger to keyboard on your next piece of technical writing, it is helpful to decide:

Am I writing for people in building mode or learning mode?

Below I’ll cover:

1. Definitions
2. Example sites
3. How to choose
4. Considerations for each

Definitions ¶

The difference is in the reader’s goals:

• Learning mode: The short-term goal is to “level-up” knowledge and capabilities, longer term goal is to better oneself. (I.E. get into school, earn a degree, ace an interview, get a promotion, be a better citizen, or achieve some other improved status in life.)
• Building mode: The short-term goal is to unblock progress in work, long term goal is to build something.

In my experience, when somebody gets to your article they are either 100% in building mode or learning mode, there is no gray area between the two.

Sometimes people will switch from building to learning after realizing they’re overwhelmed and deciding to backtrack and “learn” some core concepts required to continue “building.”

Example Sites ¶

• StackOverflow: Building Mode! although they’ve made some attempts to expand into learning mode.
• Oreilly: Learning Mode!

Which mode should you write for? ¶

There are a few cases where the choice of whether to write for learning mode or building mode is clear, for example:

• Write for building mode if your goal is to convert people to using your service or product.
• Write for learning mode if your goal is to make money by teaching people.

The rest is less clear. Here are some factors to consider when deciding which mode to write for:

Considerations for Learning Mode ¶

• Comprehensive content is valued - People typically start learning mode with a broader goal like “Learn React.” This means there’s more work for you to deliver on that promise, but if you do it well you’ll be helping a much larger group.
• Quality is key: Writing quality, presentation polish, illustrations or diagrams, all these things matter more.
• The reader has more patience: If the topic warrants it, you can have a longer article or even a course or series and readers won’t immediately abandon it.
• The author’s credibility on the topic is important. This helps reenforce the quality message.
• If you don’t have credentials, get creative: Interview people who people who do have credentials and write about what they tell you, do enough research on a specific topic that the act of doing the research itself gives you credentials. (This hack is demonstrated in the Wirecutter technique of starting every article “We spent 10,000 hours testing [some mundane product] and here is what we found.")
• Learning Mode can be purely aspirational. I.e. lots of visitors to your learning-mode work may never act on the knowledge.

Considerations for Building Mode ¶

• The best ideas for “building mode” content come from actually going through the building process yourself, taking note of stumbling blocks you encounter, and using them as topic ideas.
• Accuracy is key: Technical accuracy is paramount. Keep this in mind when writing the article and expect to maintain it over time.
• Keep it succinct: Avoid long paragraphs or a massive number of interdependent sections or steps.
• Code blocks are vital, make sure they’re nicely formatted and copy/paste-able, use the code sandwich technique for explaining code blocks.
• Images like screenshots are helpful as visual milestones or affirmation that they’re on the right track.

The Build-Learn Switcheroo: ¶

As you can see from above, it’s easier to get started helping people in “building” mode. But sometimes you’d actually prefer them to be in learning mode. (Maybe your business is teaching people, or maybe your product requires new users to go through some learning.)

Companies have succeeded by pulling a “switcheroo” where they write a “build-mode” article, but promote their “learn-mode” content around it.

This is online equivalent of walking into a hardware store looking for a powersaw, but having a helpful employee offer to walk you through the different types of saws, safety, and how to use them before selling you one.

Some readers will be impatient and just buy the saw, but some will switch to learn-mode, and everyone wins.

Can you write for both modes? ¶

I don’t think you can have a single article that works equally well for both.

In fact, a common pitfall is accidentally switching into learning mode when writing a build mode article. It’s better to keep them separate and link out to the learning mode article.

However, a former colleague of mine managed to find a very effective compromise by taking a series of building-oriented tutorials and assembling them into a larger learning-oriented book:

It was important that each [tutorial] could stand alone and serve as reference materials for developers who need a syntax check, or help Java programmers (for example) get up to speed with Python. However, because I was also creating a linked series, I wanted readers to have the opportunity to build knowledge over time.

- via Lisa Tagliaferri, How To Code in Python 3 eBook Publication: A Year Later

Conclusion ¶

Being intentional upfront about which type of reader you are writing for (Build-mode vs Learn-mode) will help you align your writing with their expectations and ultimately create more helpful and effective writing.