Share
Explore

icon picker
How to write docs people will actually read.

Your Product Brief deserves to be more than a PM bandwidth consumer.
NP
Nathan Penner
At Coda, we get excited about innovative and elegant solutions happening in docs every day. Now more than ever, we see teams coming together in docs to streamline their operations and collaborate effectively.
But as an increasing portion of our work happens in virtual spaces, how do we make sure we're reaching and engaging our audiences and co-workers successfully in those spaces?
Meeting notes can be so much more than just an exercise in frantic typing for the note-taker. And
Product Briefs
⁠
can be more than an effort to consume PM bandwidth. As the business adage goes:
"Your job communicating is not done until you've been understood."
To help make docs more useful, actionable, and delightful to readers (and Makers!), we've made quite a few changes to text in Coda these past few months and uncovered some best practices along the way.

1. Give your text clarity & navigability.

Headings in Coda have served as a great way to organize content within a doc page, but
it had been a while
⁠
since we'd made any updates to themーuntil recently. New features in Coda give headings a greater punch and help readers find what they're looking for more quickly, while providing clearer context and cleaner reading environments.

Page outlines

Adding outlines to your pages is a great way to help viewers understand how information is organized within the page if you have a long page with lots of text. Outlines update automatically when new pages are added and/or heading sizes are changed, and clicking a line-item in an outline will jump you to that page of the doc. Learn more about how to use them in
our launch post.
⁠
⁠

Collapsible content

You can "collapse" any text heading (H1, H2, or H3), table, or view (chart, calendar view, etc). When enabled, the collapsed content will remain folded-up for you and any doc viewers whenever they open the document. For example, collapsed headings in a writeup allow readers to start with a summary and then dive in to the sections most applicable to them. Or, you can create an FAQ where each question is a different heading; collapsing those headings lets readers quickly skim questions and expand to see the answer.

🏆 Tip

Use page outlines and collapsible content together to really streamline your doc for readers! For some great examples and tips on collapsible content, check out my colleague John's
awesome guide to the feature
⁠
.

2. Keep your text (and yourself) organized.

We've all been there: our doc has the perfect format and hierarchy system, but then some new required element needs to be moved, re-positioned, or re-contextualized. We've made it easier to map out an organized doc—and keep it that way.

Drag-and-drop text

Think of this feature like your leveled-up cut-and-paste.
Drag-and-drop text lets you quickly reorganize lists, tables, paragraphs of text, images, and/or headings (with their nested contents). Simply:
Hover your mouse cursor over the selection you would like to move to expose the 3-dot "kebab" menu
Bring your cursor over it to activate the "baseball mitt" cursor
Click and "grab" your text (or table, or image, etc.)
Drag it to its new location while holding down, and then
Release to "drop" your text.

You can use this to move content to the appropriate location within a doc page without holding a ton of information on your clipboard.

Checklists

Ah, the tried and true tool of organizers everywhereーchecklists! We've made it easier to insert checklists into your docs (on a new line, just type two brackets: [] ), and given them a bit more visual flair to help them standout. For example, if you've changed the color of text in a checklist, the checkbox changes to match it!
⁠
⁠
⁠

🏆 Tip

Drag-and-drop text and checklists work together nicely, especially when paired with page outlines and collapsible content. One exemplary example of this combination is using one heading for "To Do" and one collapsed heading for "Done." When you check the box for an item in "To Do" it will remain in your list as strikethrough text. You can grab the finished item, drag it to the "Done" heading, and let it live there as an archive. Out of sight, out of mind. But still accessible!

3. Understand your text as you go.

Sometimes we're limited in how much space we have to get our point across. Whether posting to social media, adhering to RFP guidelines, or simply trying to keep brevity as the soul of wit, a few data points can help us sharpen our messages.

Word count & character count

A top feature request from our community (and from Codans themselves!), we
added word count and character count
⁠
to the Statistics Panel under Doc Settings. We also enabled visibility of these counts while you type. You can also use Command+Shift+C on a Mac or Control+Shift+C on a PC to see and/or dismiss the floating word and character count.

Bonus: Word clouds

To get a sense for how frequently you're using certain words in your write-ups (or how frequently certain words/themes show-up in responses from your docs' readers), you can visualize one-or-more columns from a table as a word cloud. Here's a word cloud of the lyrics to a pretty well-known song released in 1973. Can you guess what it is?
⁠

🏆 Tip

We've heard feedback that many people would like to use word clouds in docs that are 100% text without any tables. While we look into how we can build that for you, we recommend adding a new page (which you can always hide) and inserting a table, then copying your text and pasting it into one cell in the table. You can then visualize that cell's column as a word cloud to unlock these insights for your text. That's how we made the word cloud above!

4. Give your text a little character.

Pardon the windchimey-ness, but you can make your text feel a little more like your text by taking advantage of some of our newer formatting options.

Font sizes & styles

A
few days ago
⁠
, we released a new serif font style and new large font size. The choice is yours; blog post might feel more like a blog post with a serif font, while a product brief might be more of a sans serif affair.
Font styles and sizes are configurable at the page-level. So if multiple teams are collaborating in the same doc, it's okay if one team is a bit more "small serif" and another team is more "large sans serif." You can also set defaults for every page in a doc to ensure more uniformly styling.
⁠
⁠
⁠

Quote styles

Sometimes the best way to indicate a change in voice (e.g., from the author of the primary text to someone quoted within the text) is to clearly indicate quotes:
"Block quotes are a great way to quickly indicate your text reflects something someone else said." ー Someone other than me
If your quote is an important highlight or call-out, you might wish to go a bit bigger:
"Style your text as a pull quote to really make your point jump out on the page." ーA very wise person

🏆 Tip

Use these text styling options alongside our existing options, like bold, italics, underline, strikethrough, code block, etc., to help add character and provide emphasis to the main text in your doc.

5. And don't be shy about context.

Sometimes, it's just helpful to know a bit more about a doc upfront, and to know who authored it. We launched
subtitles
⁠
and
author bylines
⁠
to facilitate just that. You can use these features on any docーinternal or published. (Scroll up a bit to see examples for this doc!)

Bonus: Some other helpful tools to engage readers

At Coda, it's fairly common that project briefs, pre-reads for alignment meetings, and docs for asynchronous note review use these drag-and-drop templates:
⁠
I've Read It
⁠
: Add this button to your doc or page so that readers can log when they've taken the time to read. (This helps ensure accountability.)
⁠
Sentiment Tracker
⁠
: Add this button to build out a table for your team to share how they're feelingーgenerally or about a specific topic or proposal. (This helps contextualize conversations stemming from the doc.)
⁠
Topic Voting
⁠
: Add this button to let people submit and upvote ideas. (We use this for everything from prioritizing Q&A, paring down our options for various ideas ,and generally making sure all opinions are logged and reviewed for our biggest decisions.)
Which of these features will you use?
0
Idea
Vote
Upvotes
1
Page Outlines
👍
0
0
2
Collapsible Content
👍
0
0
3
Drag-and-drop text
👍
0
0
4
Checklists
👍
0
0
5
Word & character count
👍
0
0
6
Word clouds
👍
0
0
7
Font sizes & styles
👍
0
0
8
Block Quotes
👍
0
0
9
Pull Quotes
👍
0
0
10
Subtitles
👍
0
0
11
Author Bylines
👍
0
0
12
"I've Read It" Button
👍
0
0
13
Sentiment Tracker
👍
0
0
14
Topic Voting (Hey, that's this one!)
👍
0
0
There are no rows in this table
⁠
This table is a demo in "play mode" for readers. When you add the table to your docs, you'll be able to accumulate votes for your entire team and sort to see the top vote-getters at the top!

Parting thoughts

Some docs might use every one of these features; some may use just one. Even simpler scenariosーlike meeting notes or blog posts draftsーbenefit from some combination of our latest text features. At the end of the day, we hope you're able to quickly and easily implement the text features that resonate most with your readers, and help you get your point across clearly and effectively.
We can't wait to see (and read!) what you make next.

1. Give your text clarity & navigability.
Page outlines
Collapsible content
🏆 Tip
2. Keep your text (and yourself) organized.
Drag-and-drop text
Checklists
🏆 Tip
3. Understand your text as you go.
Word count & character count
Bonus: Word clouds
🏆 Tip
4. Give your text a little character.
Font sizes & styles
Quote styles
🏆 Tip
5. And don't be shy about context.
Bonus: Some other helpful tools to engage readers
Which of these features will you use?
Parting thoughts
Want to print your doc?
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
CtrlP
) instead.