Skip to content

Instantly share code, notes, and snippets.

@Aaronontheweb
Last active September 27, 2023 10:55
Show Gist options
  • Star 15 You must be signed in to star a gist
  • Fork 2 You must be signed in to fork a gist
  • Save Aaronontheweb/25e131e06d6ac22b23fc1f4a2c9ff42f to your computer and use it in GitHub Desktop.
Save Aaronontheweb/25e131e06d6ac22b23fc1f4a2c9ff42f to your computer and use it in GitHub Desktop.
Technical Spec Template

Engineering Spec

💡 Use this template to help structure new engineering projects into specifications. Make sure you attach this spec to the right project - if it’s not a flagship technology then it goes under "Other Projects"

Abstract

Problem statement - what is the nature of the issue we’re going to try to solve with this specification?

💡 Tip: link to open GitHub issues or support tickets if there are any. Anything that can share the problem in the users’ own words is very helpful here.

Business impact - why is this project worth working on?

Goals

What are the goals of this project upon completion?

💡 A simple bulleted list is usually sufficient.

Requirements

What are some of the functional and non-functional (i.e. budget, environment) constraints on this project that stakeholders need to be aware of?

Challenges

What are the cost-drivers behind this project? What is going to make it difficult or expensive?

Implementation Plan

Now that you’ve laid out all of the challenges for this spec and proposed some solutions for each, what is your proposed implementation plan and why?

💡 You need to make a coherent, end-to-end delivery plan that includes [cost-benefits analysis](https://www.investopedia.com/terms/c/cost-benefitanalysis.asp) of each of the possible solutions you proposed and why. “Why should we do it this way and not the others?”

If you can’t explain your reasoning, then you’ve not finished your homework yet. Keep going.

The steps of the implementation plan need to be spelled out in order:

  1. Step 1
    1. Reasoning...
    2. Relevant detail....
    3. Testing plan...
  2. Step 2...

Bailout Condition

We can’t spend forever working on any individual project - under what conditions are we going to stop working on the current implementation plan and reevaluate? How much time? Do we bail out if we can’t successfully complete one of the earlier steps in the implementation plan because it turns out to be technically infeasible? When do you raise the white flag and ask for help?

💡 **REQUIRED** - you have to specify how you would limit the time spent on a project in order to work on it.

Post-Mortem

💡 Complete this section after we’ve bailed out or successfully delivered the project. Write up how things went, what went well, and what did not.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment