🚧 Look for this icon for tips on how to craft an ideal PDR-style proposal. Make sure that you remove these 🚧 hints before publishing! The non-blockquoted text is meant to be a prompt and need not be kept if not appropriate for the context.
🚧 Always begin the title with "Proposal: " and summarize the issue without stating the solution outright unless the solution is obvious and without a realistic alternative. Assume familiarity with terms but make obvious the benefits of acting on the proposal. Stating the date here conveys that the assumptions and research may lose accuracy past that date.
A proposal by author(s) for consideration by date.
🚧 This section summarizes the document in three quickly consumable aspects: the problem, the author's diagnosis, and the author's explored and recommended remedies. Before getting into the PDR, explain the premise. Examples: "I want to be healthy." "Code should be reviewed before entering the mainline repository in order to ensure that contributions are of the highest quality."
We all know that…
🚧 Describe the problem in concrete terms. Be factual, cite data but do not explain the data: that goes in the Research and Exploration section. Keep this problem description succinct and free of opinionated language. Examples: "I am lightheaded." "Code Reviews are open for weeks without comments, approvals, or merges."
I observed that…
🚧 Describe what your research leads you to believe is the problem. Do not describe secondary problems or suggest resolutions to individual diagnoses: those go in the other sections. Example: "I am bleeding." "The team does not prioritize reviewing and instead prefers to generate new code until blocked."
My observation and research lead me to believe that…
🚧 Summarize the realistic options presented herein but always highlight the recommended course of action. Ideally, this whole executive summary section could be read as three sentences. Example: "I should apply a bandage." "The team should set aside the first 30 minutes of their day to conduct reviews, skipping this time block only when there are no reviews to be done."
My research leads me to recommend that…
🚧 Describe in as much detail as necessary the current state of the world. Describe the problem and its effects on schedules, timelines, budgets, sanity, and more. Focus on risks and uncertainty that cause this to be a problem worth fixing.
Currently, …
🚧 Describe in as much detail as necessary the desired state after any proposed remedy is applied. All remedies should achieve this goal but perhaps vary in the three categories: cost, speed, and correctness. Those remedies should not be outlined here.
Any proposed solution will…
🚧 This is the meat of the document.
🚧 Summarize possible solutions here. One option should always be "do nothing" and explain the ramifications of inaction. Always list these by number so that they can be easily referenced in the summary and in subsequent discussion.
These are the options to reach an outcome that achieves the desired state.
- Do nothing.
- …
🚧 Use this section to describe the problem, its cause, and your recommended remedy, referencing the option number from the options section.
In summary, X causes a problem. I recommend option #3 because it is the perfect balance of speed, cost, and correctness.