🔧 How to write a great one-pager

🕛 Zeit seit Veröffentlichung: 53 Tage, 13 Stunden 42 Minuten
📆 Veröffentlicht am: 13.10.2024 um 01:01 Uhr
Nachrichtenbereich: 🔧 Programmierung
🔗 Quelle: dev.to

One-pagers are the fastest mechanism the software industry uses to gain alignment. A one-pager is a document which outlines a problem's context and exposes potential solutions to solve the problem. After a one-pager is made available, it is often presented in a review process to drive toward a decision.

This one-pager outlines the non-obvious rules for writing one-pagers.

1. Assume your audience is 2-3x less informed than you believe.

In doing so, you will surface basic assumptions the group makes. This allows the group to question assumptions before asserting a direction for the review. Many one-pagers are shared beyond the scope the author intended. By writing for a less-informed audience, you help non-technical roles understand why the work needs to be done and what areas of the system are impacted.

2. Adopt egoless writing.

Gerald Weinberg in, The Psychology of Computer Programming, recounts a story where a technical leader wrote twenty lines of code. When another engineer reviewed the code, she found eleven major errors. Instead of the leader defending their choices, they laughed and shared the news with everyone in the office, praising the reviewer for finding so many mistakes.

This is an example of egoless programming. The author celebrated the mistakes pointed out in the code they wrote. When we write one-pagers, we aim to do the same. Every criticism is not a criticism of the author, but of the physical words on the page. Every comment should be treated as an opportunity for celebration.

3. The author owns the document.

A principle I picked up from Amazon: the one who is responsible for writing the document has the authority to determine what the document says. Reviewers find places the document needs to change, but do not decide how to resolve comments. This is most effective when practiced alongside egoless writing.

4. Suggest two alternatives to a course of action.

When only one option is present, reviewers tend to wonder whether the author explored other options and request more research. With two options, reviewers tend to “pick sides” instead of exploring tradeoffs. Three or more options communicates that enough research has been done and it helps reviewers not become attached to any of the options.¹

Mark the first option as recommended. Tell why that option is recommended. Include graphs, risks, and tradeoffs.

5. If someone suggests a nitpick, find a way to accept it.

Anything besides content should be resolved as quickly as possible so as to not detract from the review. Unless it changes the meaning, accept whatever suggestions people have and move on. If it does change the meaning and you can't accept it at face value, message the reviewer and suggest a third way to phrase things. If one person thought the original phrasing was confusing, there are more who haven’t spoken up.

6. Include graphs.

If you don’t include graphs and there’s an opportunity to, someone will request it. Make the graphs beforehand so that you can focus on the content during reviews.

Some people understand the information better after looking at graphs. Consider “graph making” an exercise in accessibility if nothing else.

7. One-pagers are as short as reasonable.

Few one-pagers are actually only one page. However, strive to make them as short as you can. An easy way to do this is to eliminate all tangents beyond the scope of the overview. If you follow the format below, all information should guide reviewers toward making a decision.

8. Follow a format

Format changes per subject, but following this pattern as much as reasonable leads to higher quality reviews. There are a few "tedious" sections (overview, graphs, what the system looks like today), but including these eliminates questions unrelated to the topic.

1. Overview: One-to-two paragraphs about the area we’re working in, the problem, the services involved, and any other documents or links that are relevant to the discussion.
2. Current user flow: This may be a section with multiple subheadings depending on the scope of the change. Talk about how data flows through your system. Bring graphs.
3. Answer questions preemptively: Things like, “what happens if we do nothing?”, “how long do we have to act?”, “is there any off-the-shelf software we could use?”, “what have we tried in the past?”. Make each heading a sentence with the question being answered. That way curious minds can navigate using the document outline.
4. Proposed changes: as mentioned previously, bring at least three alternatives and mark your recommended path in the heading. Try to use one graph per alternative.

Special thank you to LTK for allowing me to publish this. I originally wrote it as internal documentation and asked whether it would be ok to also publish it here.

1. This came out of a mentoring session I had with Diana Larsen. In 2020 I asked her how to help my teammates fight for “the right thing” instead of their own perspectives. Her advice was to find a third alternative even if it was a weaker suggestion. ↩

...