Wrapp Engineering Proposals

When I read about Documenting Architecture Decisions over at Relevance I immediately thought it was a great idea. We promptly adopted our own version at Wrapp and called it Wrapp Engineering Proposals, or WEPs for short. We use WEPs as a decision making tool not only for architectural decisions but for anything that needs to be agreed on by the whole team.

Some examples of WEP topics include how to write documentation like commit messages, READMEs and even WEPs; architectural requirements like implement logging in services and how to encode monetary values; and security requirements like how to properly use encryption and setup authentication mechanisms.

Here are our instructions for creating a WEP, stolen from our WEP on WEPs:

1. Somebody has an idea for a change.
2. That person talks to other people and concludes their change is good.
3. The person writes a WEP document describing their change, pushes it to Github, opens a pull request, and asks everybody to review it.
4. Everybody (who is interested) discusses the WEP. Discussion can take place both IRL and in the pull request.
5. When enough people seem to be in agreement the decision is automatically considered approved. (Impatient participants can speed up this step by harassing their co-workers to participate in the discussion.)
6. The person merges the pull request so that everybody knows that it is now approved.

From this point on the WEP is considered approved and everybody must do their best to follow it, until it is updated or deprecated by a new round of steps 4–6 above.

There are some drawbacks to the WEP process. For one thing it is fairly slow, usually requiring at least one week from draft to approval. There is also a risk that the discussion deadlocks, although this has not happened yet, and we stress that the discussion must remain constructive — it is in everybody’s interest that a decision is reached.

Some may disagree with the approval not being based on a vote but simply the author’s feeling of having sufficient backing and minimal opposition. This is because we want to be able to make decisions even if not everybody has chosen to respond or is in total agreement. Again, it is in everybody’s interest that the discussion flows smoothly. After all, WEPs can be reverted as easily as they were approved.

WEPs also have some very good benefits, of course, like providing a papertrail of decisions that we can return to when needed, or use to quickly get new colleagues up to speed. We’re also hoping that the asynchronous nature of the process will allow participants the opportunity to think deeply about the decision and to clearly articulate their arguments, creating a more nuanced discussion free from knee-jerk reactions.

Personally, I’m hoping that the structured approach will encourage those in our team who do not usually participate in open discussions to do so. After all, we want a decision making process that is open for everybody. Perhaps in the long run this will lead to better decisions being made, but I firmly believe that we will be having more fun and a better work place if we can get everybody involved.

Now that I have tried to explain how great the WEP process is, you may be suprised to hear that we do not use it much. In addition to WEPs we have recurring retrospective meetings where the focus is usually on teamwork, and where decisions can be made on the fly. There is also lots of discussion going on on Flowdock, and if a decision seems trivial enough then it may simply be approved without formalities by the participants there. WEPs are usually called for when there is a need for clear, written documentation, or a proposal must be drafted in order to get the discussion rolling.

But the majority of the decisions we make in the Wrapp engineering team are simply not made at the team level. Ideally any day-to-day decisions can be taken directly and informally by the person or group that is affected by them. Examples of decisions that do not require team-wide decisions are whether or not to create a new service; which programming language, libraries and databases to use; and how many tests to write. Engineers who are about to make such decisions are naturally free to seek the advice of others, and even encouraged to, but in the end we are counting on them to make the best decision in the context of their work of which they are the experts.

The ability for anybody on the team to make immediate decisions on the limited scope on which they are working is a great thing. Regardless of how they are performed, team discussions take lots of time from more interesting work. We believe that engineering is the most satisfying when you are able to solve problems yourself and quickly see the results, and enabling these things is an important goal of our microservice strategy. As a bonus, this seems to lead to more heterogeneously designed services, which comes with a price but also gives us great opportunities to evaluate different tools and approaches.

For the few times when we do need to get the team onboard for a decision, especially of the more technical variety, WEPs do seem to have their place. Compared to retrospectives or Flowdock, the process seems more likely to hold up as our engineering team grows. If we need to update the WEP process along the way, well, we will simply write a new WEP about it.