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 authorGoals: 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?
Posted on 8 January 2021, in technical writing and tagged design doc, doc plan, documentation plan, one-pager, technical communication, technical documentation, technical writing. Bookmark the permalink. 4 Comments.
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
Pingback: The power of a doc plan or design doc | ffeathers
Pingback: Role of a technical lead (TL) | ffeathers