Sam Beil

On onboarding developers

Writing "set up [name of a tool for developers]" in a pull request description proposing a new product in a project might get the job done, but it isn't a strategy for success—it's unkind and unprofessional. When I suggest including a new product in a project, I put my reputation on the line—I want the product to make an excellent first impression, inspire confidence, and do what it promises.

I want people to feel taken care of. A clear description of how to start using the tool in a pull request description helps, but it takes a lot of time to write. More than once, I’ve found myself setting up a new account to describe how to get a tool up and running step by step. There must be more people like me.

Have you considered adding a snippet for pull request descriptions to your onboarding process?

Most likely, someone has already thought of this and it even has a name of its own, but I haven't encountered it yet.

Hookdeck inspired me to write these words. Their onboarding is excellent, but I caught myself setting up a new account to write this:


  1. Create a Hookdeck account (you can skip the onboarding questions)
  2. Name your workspace (below the onboarding questions)
  3. Choose Create Workspace
  4. Select Create Connection
  5. Name your source ACME
  6. Turn on verification
  7. Select ACME as the verification method
  8. Enter ACME_SECRET from your .env as Webhook Signing Secret
  9. Name your destination (I used my first name and ACME here)
  10. Set Destination Type to CLI
  11. Set CLI Path to /just/an/example
  12. Choose Save
  13. Install Hookdeck CLI (I just did brew install hookdeck/hookdeck/hookdeck on macOS)
  14. Run hookdeck login
  15. Run hookdeck listen 5173 ACME


December 11, 2023

Tags: onboarding, developer, software, engineers, dev, devrel, github, pull request