Whitepaper/Design Doc Guide

Title and People

Overview

A high level summary that every engineer at the company should understand and use to decide if it’s useful for them to read the rest of the doc. It should be 3 paragraphs max.

Context

A description of the problem at hand, why this project is necessary, what people need to know to assess this project, and how it fits into the technical strategy, product strategy, or the team’s quarterly goals.

Goals and Non-Goals

The Goals section should:

  • describe the user-driven impact of your project — where your user might be another engineering team or even another technical system
  • specify how to measure success using metrics

Non-Goals are equally important to describe which problems you won’t be fixing so everyone is on the same page.

Milestones

A list of measurable checkpoints, so the course staff can skim it and know roughly when different parts of the project will be done.

Use calendar dates so you take into account unrelated delays, vacations, meetings, and so on. It should look something like this:

Start Date: June 7, 2018

Milestone 1 — New system MVP running in dark-mode: June 28, 2018

Milestone 2 - Retire old system: July 4th, 2018End Date: Add feature X, Y, Z to new system: July 14th, 2018

Proposed Solution

Some people call this the Technical Architecture section. Try to walk through a user story to concretize this. Feel free to include many sub-sections and diagrams.

Provide a big picture first, then fill in lots of details. Aim for a world where you can write this, then take a vacation on some deserted island, and another engineer on the team can just read it and implement the solution as you described.

You should describe tooling, infrastructure chosen, blockchain/fintech/disruptive framework you will use, front end, back end, and any external cloud or network you want to leverage. Show it in a diagram or chart, insert mock-up screenshot from the prototype deliverable, some code snippets.

Resources for this section:

Open Questions

Any open issues that you aren’t sure about, contentious decisions that you’d like readers to weigh in on, suggested future work, and so on.