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?