Writing guide for Product Managers, Part 2

Actionable tips for adding structure and flow to your product documentation.

Feb 8, 2022

Hello there! Welcome to my eclectic newsletter. My name is Ev, and every week or so I publish a blog about technology and product, with a dash of strategy and a pinch of trends.

🎤 If you have a question, you can ask me in the comments section below.

Welcome to Part 2 of the Writing Guide for Product Managers. In Part 1 we talked about 10 principles of good writing. (If you missed it, read it here.)

In today’s newsletter I’ll share actionable techniques that you can use to create structure and flow in your written work.

The reader’s journey

Product reading is not sequential. Your readers scan through documents and jump from one section to another. The document you wrote might be important to you, but to them it’s one of many they have to read today. Once they open it, several questions will be on their mind:

Do I need to read this?
How deeply? Which sections can I skip? Which sections can I skim? Which ones should I read thoroughly?
Do I need to provide feedback?

Only one part of your job as a product writer is helping readers gain new information. Another part is helping them understand whether they need that information at all. This is where structure comes in.

Good structure helps readers to navigate the document, and to decide how they should work with it. Below are the simple techniques for adding structure to your written documentation.

#1 Build your information architecture upfront

Each document you create has an internal information architecture, and your readers rely on it to make connections between ideas in your narrative. Well-designed structure is like a series of bridges that guide the reader from one section, bullet point, or footnote to another. On the other hand, poorly crafted information architecture makes it hard to understand the document. It’s like swimming in an endless pool of lukewarm drinkable yogurt. Yuck.

When working on each new product document, I like to outline the structure before committing any ideas to paper. That helps me catch inconsistencies in my thought process and find the best way to sequence the sections and chunk the narrative.

#2 Bullet points: no more than 3, with summary

From a stylistic perspective, I’m not a fan of bullet points. They are a sign of unimaginative utilitarian writing that has been stripped of soul in exchange for function. While I avoid them when I can, their bare utility sometimes comes handy when explaining

categories,
options,
sequences.

Despite their lack of style, bullet points work well when you want the readers to quickly scan the text and pick the elements of it that they deem relevant.

Note: I’m deliberately not mentioning checklists in this section, because that’s a different, specialized use case.

#3 Be specific

Being specific means not leaving anything to interpretation. Let’s look at this sentence: “Significant number of users performed Action Z after the release”. What is a “significant number”? What does “after the release” mean? We can edit that sentence and get straight to the point: “X% of users performed Action Z within 1 week after the release”.

#4 Add a TL;DR

Some of your readers will want to know every single detail in your document. Others will only seek a high-level summary. Unfortunately, when they see your doc for the first time, they won’t yet know whether they want to read the whole thing or not. You need to help them figure that out.

A three-sentence summary that contains the main idea of your business opus will help the readers to decide whether they want to be lightly informed or deeply engaged.

#5 Emphasize in bold to help readers skim

Sadly, readers don’t dedicate all of their brain cycles to our writing. Slack and email notifications, domestic work-from-home or office interruptions chip away from their attention span, and we, writers, are left with scraps. It won’t get better, and all that’s left is to adjust and make use of what we have.

Emphasizing text in bold is a crude yet effective way to do just that and to point the inattentive reader towards the most important ideas in our text. While the readers may not grasp the details, skimming through key ideas is enough to equip them with basic understanding of our message. Not perfect, but good enough for them to not feel lost in that all-week meeting that started last Monday.

#6 Add flow charts to help skim

A lot of product work hinges on our ability to understand user journeys, data flows, processes. We tend to talk about all of those things, even when the best way to share our insight is to show our readers a flow chart.

BONUS: Style guide for your slides

I’m not a fan of slides, but here are several formatting tricks that make slide decks easier to digest:

Each slide should make only one point.
Slide titles are your headlines. (Remember the pyramid principle?)
Text within the body of a slide should be the same size
All titles within the deck should be the less than 2 lines of text
Use visuals and infographics when you can
In the slide body, avoid long blocks of texts (more than 2 lines)