Writing a one-pager to pitch a doc idea

As a technical writer, I’ve sometimes found it useful to write a short document describing an idea or a proposal. The target length for such a document is one page. Hence the name, one-pager. In some situations, a one-pager is a good alternative to a doc plan.

This post is about one-pagers used in the context of technical writing. In other contexts, a one-pager may be a pitch for a company or a student’s summary of a lecture.

Quip: An engineer pointed out that one of my one-pagers was technically a two-pager. (It was actually about one and a third pages long.) I responded that I could fix that by reducing the font size. 🙂

For me, the purpose of a one-pager is to express an idea and get input on the idea. For example, I’d write a one-pager when a doc plan would be too heavy-weight, but I want to get feedback before starting the documentation update.

A one-pager isn’t the place for a detailed design — that’d go in a doc plan or a design doc. (See my post about doc plans.) Rather, a one-pager is useful to coalesce my own thoughts about an idea, and to get feedback from my colleagues about the overall idea before I go ahead and implement it.

For example, I’d create a one-pager to propose one of the following:

  • A new tutorial for a use case that we don’t yet cover in the documentation.
  • A new type of tutorial that follows a different pattern from the other tutorials in the documentation set.
  • A change of tone in a particular document or documentation set. I’d describe the tone of the current documentation, the effect that the tone is having on readers, the new tone that I’m proposing, and the reason for the change.
  • An event, such as a doc sprint. I’d describe the purpose and format of the event in order to gauge support before plunging into further planning.

What does a one-pager look like? Well, firstly, it’s short and to the point. Because it’s so short, a one-pager often doesn’t include headings. My one-pagers tend to look like this:

Title (For example: One-pager: New tutorial type for Foo users)
Date and author

Goals: A business statement of the effect you want to achieve. (For example: customer retention, increased adoption, etc.)

A short, motivational callout, often in large text and a different style from the rest of the doc. (For example: We want to help customers use Foo when things go wrong.)

A succinct description of the idea or proposal. This is the main part of the one-pager. Start with a descriptive paragraph, followed by bullet points to capture the main points in your proposal. As well as being a useful short form, a bulleted list gives visual emphasis that this is the core of the one-pager.

In scope: Areas that are in scope for this proposal. If you don’t have anything to put here, leave out this section.

Out of scope: Any areas that are out of scope. The goal of this section is to ensure there are no misunderstandings between you and your stakeholders. If you don’t have anything to put here, leave out this section.

References: a list of relevant documents

Have you ever written a one-pager, or have you felt the need of such a document type in the past?

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 8 January 2021, in technical writing and tagged , , , , , , . Bookmark the permalink. 3 Comments.

  1. Sarah, that’s a really good tip, and happy new year!

    When I’m working on something new, I talk to the product manager or whoever’s in charge of the project and make my notes. While I’ll often check my understanding with their goals etc, I don’t normally write it down like this. Guess I will from now on. 🙂

    • Hallo Mick, and a very happy 2021 to you too!

      I’m so glad this is a useful tip. One-pagers are great for… getting everyone on the same page. (I couldn’t resist that!)

      Cheers
      Sarah

  1. Pingback: The power of a doc plan or design doc | ffeathers

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: