Revise Heroku deployment documentation to emphasize key points

[hancush]

Documentation request

Our Heroku docs are awesome, but there are a few spots where it's easy to miss crucial information, e.g., you must have the manifest plugin installed to build an app from heroku.yml. (We say to check for it, but not why it's important.) This is a bummer because Heroku won't raise any exceptions if you create an app with the --manifest flag but don't have the plugin installed, leading to a confusing situation where your new app doesn't have a database.

Let's do a quick audit of critical information, then add supporting headings and/or other emphasis and explanation to those sections, so it's less easy to miss important steps.

TODO

• [x] Clarify that you must install the manifest plugin to build your app and dependent services from heroku.yml. Might also be nice to add a section on troubleshooting this particular issue.
• [x] Add a heading and subheadings for configuring secrets in apps and review apps. It's currently lumped in with creating apps and pipelines.

@smcalilly, I'd appreciate your suggestions here, as well, since you most recently used these docs. Would you mind taking a pass at the first revision, per our conversation about highlighting key information at the outset and repeating it throughout the document?

[smcalilly]

@hancush This doc is already doing everything we discussed, so it just needs some key information highlighted in a different way.

Here is how I read this doc. I scanned all the steps and saw that a lot of the steps were for configuring an existing app to use Heroku. That's important information to know for learning or debugging a deployment, but it's not relevant if the app is already configured via the cookie cutter template.

So I skipped forward to the information that I needed: deploy a configured app via the Heroku CLI. I installed the Heroku CLI and completely missed the manifest plugin requirement. I was wrong to go to the Heroku site and install the CLI as they instruct, instead of following the manifest plugin step.

The doc already has the top level contents: https://github.com/datamade/how-to/blob/master/heroku/deploy-a-django-app.md#contents. To that section, I might add a system requirement heading to highlight the manifest plugin requirement.

It could also be separated into two distinguishing sections:

1. a complete guide, as it already is
2. a quick start or TLDR about how to do this from your CLI for a pre-configured app. This section is that, but it's somewhat buried in the complete guide.

The "Provision Heroku resources" section makes sense and shouldn't change. I'm wondering the best way to point to that information for a quick start – maybe just have a section with a few bits of text and links to the create apps and pipelines to your project section?

Personally, I need to slow down when reading information like this, but I also think that other people in the future might scan and miss information, too.

[hancush]

@smcalilly

Here is how I read this doc. I scanned all the steps and saw that a lot of the steps were for configuring an existing app to use Heroku. That's important information to know for learning or debugging a deployment, but it's not relevant if the app is already configured via the cookie cutter template.

This is really important! For us, the most common use case will be that we already have the right setup from the template. What if we rearranged these docs so "Provision Heroku resources" comes first, and followed by migrating a legacy application and setting up CI?

I also think we should revise steps from double checking to declarative steps, i.e., Ensure the Heroku CLI is installed -> Install the Heroku CLI and manifest plugin. That, in addition to a note that you must install the plugin for our apps to build from heroku.yml, will make it harder to miss that step. I think a corresponding item in the troubleshooting section would also be helpful, e.g., "Help! My application doesn't have a database!"

[hancush]

Another thought: The Provision Heroku resources section contains a mix of steps you need to do when migrating an app (e.g., adding heroku.yml and app.json) and regular deployment steps. We should relocate steps that are redundant with the template to the section on migrating a legacy application.

[smcalilly]

Closed with PR #167.

[hancush]

@smcalilly Perhaps counterintuitive but I'm going to keep this open and move it into the Done column of our project board so we can track what we landed this cycle. This isn't written done anywhere but it would be a good addition to the README. I'll open an issue to add it.