Problem Statement & Solution

A step by step guide how to come up with a proposal for major technical/architectural change to present to the team. This problem statement will help you with three things:

• produce shared understanding about the technical problem with the other developers
• give you a basis for discussing the technical solution with the other developers
• expose your ideas as early as possible so you can benefit from the collective knowledge of the other developers

A good rule of thumb for when some change is major or not is to estimate how much time would be wasted if the pull request was rejected. If it's a couple of hours then you can probably dive head first and eat the loss in the worst case. Otherwise, producing a problem statement and discuss it with the other developers will save everyone lots of time.

Producing a problem statement is as easy as:

1. Copy this document to a another wiki page, etherpad, presentation or something
2. Answer the questions it poses as accurately as you can
3. Present the document to other developers of the team
4. Incorporate the feedback they give you. Present it again. Repeat until happy.
5. Implement

Please stick to this format so it's easier for all of us to get used to this.

Reality?

In this section you should describe the state of the workflow and user interaction as of today. The more accurate you describe the reality, the more exact you will understand the consequences in the next section.

• How is the workflow to do this right now?
• Which kind of users are involved?
• Which models/services are involved?
• What other OBS subsystem (delayed jobs, sphinx, caches etc.) is involved?

Consequences?

In this section you should describe the downsides of the reality as of today. The more exact you understand the consequences, the more precise you will be able to illustrate the future in the next section.

Why do we need to change the workflow that we have right now?

• What is wrong with the workflow?
• What are the problems with how the models/services are used?
• What are the pain points with involved OBS subsystems?

Future?

In this section you should describe the desired state of the workflow and user interaction in the future. The more precise you illustrate the future, the more solid your proposal how to implement in the next section will be.

• How should the workflow to do this be in the future?
• Which kind of users are involved?
• Which models/services are involved?
• What other OBS subsystem (delayed jobs, sphinx, caches etc.) is involved?

Proposal!

Describe one (the best 🚀) potential way to make the future happen, you described in the previous section.

• What do we have to change to be able to implement this new workflow?
• Which models/classes will be involved?
• What are the needed changes to any other OBS subsystem (delayed jobs, sphinx, caches etc.)?

Please note: Try to avoid to propose more than one solution. You just offload the decision to the developers you present this to, this is not nice. You are the person/group that analyzed this. You have everything at hand to decide now.

• If you can not decide because you can not foresee the consequences of your decision, research more
• If you have two competing solutions choose the one with less severe consequences
• If there are no foreseeable consequences to two competing solutions, propose the one you like more, the one that feels better to you.

Once you present this, the others will tell you if they know/foresee something you have not. Then we can adapt.