Skip to main content

Service Name

Overview​

What does the service do? What are the major technologies is it built on? At a high-level, How does it fit into the rest of our services?

Related Services:

  • <insert link to related service>
  • <insert link to related service>

Where is the Code?​

Links to major repositories. Don't get too crazy listing everything.

Example:

Ownership​

CODEOWNERS? Repo Maintainers? Slack Channels?

Where to find the team:

  • Mailing list? e.g. myteam@flipsidecrypto.com
  • Slack team and rooms? e.g. #team-myteam on Flipside Slack

Where does it Run?​

What 3rd party services (e.g. vercel) or cloud services (e.g. S3, k8s) Is the answer different for different parts of the service?

Where is data stored?​

S3, postgres, 3rd party service, um... google sheets?

How is it deployed?​

Example:

Github actions are defined in the .github/actions and are managed by Terraform. The production deployments are kicked off by pushing annotated git tags to master, a docker image is tagged with that same tag in Amazon ECR. New images trigger a deployment into a kubernetes cluster.

What DNS addresses are supported?​

Example:

  • service.flipsidecrypto.com (production)
  • service.staging.flipsidecrypto.com (staging)
  • service.preview.flipsidecrypto.com (preview)

Addtional Documentation​

This should be a link to the root of your team's documentation. A README.md at the root of your main project would be a good option here. Good project documentation will save you from questions, help you onboard new team members, and save future-you from having to remember every little detail about how your service works.

Check out the documentation checklist if you're wondering what to include.

If your service has an github wiki operating manual (hint: it's a good idea), you should link it here, too. Operator manuals helpful for folks on-call and usually define typical troubleshooting scenarios, how to restart, redeploy, kick it fonzi style. Unless you fancy being called up in the middle of the night to help figure out an issue, its in your best interest to document this kind of stuff for the on call and onboarding engineers.