July 19th, 2022

Microspeak: The one-pager

At Microsoft, a one-pager is an overview document. It is usually prepared during the early stages of a project or feature in order to share what is known, what is not known, and what the current ideas are. It is not intended to be a deep dive.

Different teams use different document templates for their one-pager documents. It might contain an elevator pitch, which is a brief statement of the problem and the desired outcome. In the business world, an elevator pitch is a brief but compelling description of an idea, product, or company, so-named because it is a speech you can give to someone important during the course of an elevator ride. In a one-pager, it is a brief but compelling description of your project or feature.

The other parts of the one-pager may be devoted to things like customer research results, a list of alternative solutions, the goals and non-goals of the feature, the project’s success metrics, and any external dependencies that would prevent the project from succeeding.

What I find particularly amusing is that the one-pager almost never fits on a single page. In many cases, the blank template is itself already longer than a page!

Some time ago, I was called upon to be one of several presenters, each of whom had a ten-minute time slot to present their one-pagers. I was the only one who managed to fit my one-pager onto a single page. It turns out that writing concisely takes work, and limiting yourself to one page forces you to make hard decisions about what is most important.

Bonus chatter: I think part of the reason for sprawling one-pagers is that people feel that they have to write more about a subject in order to prove that they have thought hard about it. They treat the document as a “proof of work” rather than as a means of concise communication. Another temptation is to anticipate all possible questions and pre-emptively answer them in the document. It’s true that your one-pager should call out rejected alternatives, but you don’t have to write a paragraph-long justification for rejecting each one. If you feel the need to provide “proof of work”, move it to a supplement or appendix.

Author

Raymond has been involved in the evolution of Windows for more than 30 years. In 2003, he began a Web site known as The Old New Thing which has grown in popularity far beyond his wildest imagination, a development which still gives him the heebie-jeebies. The Web site spawned a book, coincidentally also titled The Old New Thing (Addison Wesley 2007). He occasionally appears on the Windows Dev Docs Twitter account to tell stories which convey no useful information.

4 comments

Discussion is closed. Login to edit/delete existing comments.

  • amoskevitz

    The company I work for has a document called a “One Page Summary”, I have yet to see one shorter than 4 pages.

  • Lim Pro

    Impressive👍

  • Roger B

    *managers as they read this*: “yadda yadda, proof of work…”
    Manager: Ah, I know this! Maybe if we put one pagers on the block-chain teams won’t have to provide the proof of work themselves!!111

  • Claudio Andre Heckler

    That reminded me of this quote, which I've known for many years (I believe I read it on "Reader's Digest" over 30 years ago, but I'm not sure)

    “How long does it take you to prepare one of your speeches?” asked a friend of President Wilson not long ago.

    “That depends on the length of the speech,” answered the President. “If it is a ten-minute speech it takes me all of two weeks to prepare it; if...

    Read more