As we expand our engineering team, internal comms (Principles of Internal Communications (Comms) - August 2020) gets harder, so it's important that we align on some best practices to ensure that everyone at the company feels informed and has the information they need in order to be successful.
Stakeholder communication between engineering and non-technical business units is notoriously hard, because non-technical people don't understand a lot of the terminology and complexity that comes with building software. So we as an engineering team need to be extra careful to communicate effectively and regularly.
This document is written for engineers, so we'll only briefly touch on what a pull request is. In short, a pull request is a request by an engineer to merge something into the codebase. An engineer works on a version of the app on their computer, and when they're finished working on their task, they "open a pull request" to allow others on the team to review it before it gets merged into the main codebase.
Below we'll go through a few best practices we've found that improve stakeholder communication
A common approach to increase visibility is to open a pull request while something is a work in progress and push to the branch at least once a day. This is so common, in fact, that GitHub introduced "draft" mode for pull requests in 2019, which designates a pull request as a work in progress that's not yet ready for review or merge (see below).
This approach doesn't scale to a massive company, but it should be effective for us until we have ~30 developers, at which point we can rethink how we handle things.
Smaller PRs necessarily mean that you'll release more often, and can potentially share progress with product/ops/etc along the way. This also makes PR reviews easier, since each change is more self-contained.
We also strongly encourage you to add screenshots or looms of partial progress. This not only gives greater visibility to the team about the state of your project, but they can be used outside of engineering in case we need to quickly show someone (either another employee or a partner) what a particular feature looks like.
At our stage, it is often the case that specs are not clearly defined. A scenario we've run into in the past that we'd like to avoid:
David sends a spec to engineering to add animations to the app. The spec contains all possible animations for the app. What David wants is to have only the simple animations implemented, which should take about 2 days, but this is not communicated effectively.
The engineer spends 10 days working on animations and delivers the updates as defined in the spec. David and the team are frustrated that so many engineering resources went into adding animations that are not high priority caused by a miscommunication.
If this was done with a draft pull request with screen shots or looms of partial implementations added to the draft, David could have seen that the parts he wanted implemented were finished on day 2, and he could have redirected our engineering resources to work on other, higher priority tasks.
Here's an example of a pull request that includes a loom of the final deliverable, which gives everyone the ability to fully understand and appreciate the functionality without the need to pull down the branch and run it locally. This is a huge time saver for everyone else on the team!
https://github.com/levelshealth/levels/pull/1200
