{"id":106873,"date":"2022-07-19T07:00:00","date_gmt":"2022-07-19T14:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/oldnewthing\/?p=106873"},"modified":"2022-07-19T07:36:49","modified_gmt":"2022-07-19T14:36:49","slug":"20220719-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20220719-00\/?p=106873","title":{"rendered":"Microspeak: The one-pager"},"content":{"rendered":"

At Microsoft, a one-pager<\/i> 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<\/i>.<\/p>\n

Different teams use different document templates for their one-pager documents. It might contain an elevator pitch<\/i>, which is a brief statement of the problem and the desired outcome. In the business world, an elevator pitch<\/a> 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.<\/p>\n

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.<\/p>\n

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!<\/p>\n

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<\/a>, and limiting yourself to one page forces you to make hard decisions about what is most important.<\/p>\n

Bonus chatter<\/b>: 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.<\/p>\n","protected":false},"excerpt":{"rendered":"

Rarely ever one page long.<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[105,26],"class_list":["post-106873","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-microspeak","tag-other"],"acf":[],"blog_post_summary":"

Rarely ever one page long.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/106873","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=106873"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/106873\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=106873"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=106873"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=106873"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}