How to run a Practice Review Workshop

Review ongoing battles

The first is to review ongoing battles started in previous Practrices Review Workshops. People could vote or add arguments in favor or against the adoption of the best practice. It's now time to decide whether you should keep this practice or not. If you decide to discard it, we advise you to record your motivations to keep track of this technical decision.

Review developers' contributions to best practices

The Workshop animator will go through each identified practice and invites the author of the contributor to justify their proposal. Each contribution can be related to either a new practice, or an existing one, and looks like this in Promyze:

Step 1: Make a decision on new practices

New practices are tagged with a star ✨icon.
If it's a new practice, you have to decide as a team among the following choices :
  • Validate this practice in your repository of best practices.
  • Decline this practice, If you think this is not relevant for your project
  • Start a battle, if you're not ready yet to decide
You can also update the best practice name and definition at any time if you think that adjustments are necessary after discussions within your team.
Remember the practice editor supports Markdown

Step 2: Validate the contribution

If the contribution concerns an existing practice, you can decide whether the example or counter-example should be kept in the documentation of the best practice.
Indeed, it might happen that a suggested best practice makes sense if we only consider its name and its description, but the source code example does not actually make sense or does not reflect it. When it's the case, you can just delete this example, by clicking on the trash icon.

Step 3: Configure automatic suggestions

You'll find a dedicated section on that topic, but during a workshop, you can:
  • Disable the automatic suggestion configuration for the current source code example, meaning Promyze won't reuse its keywords
  • Add a regular expression to make this recognition possible
If the regular expression tends to be complex to set up, we advise that someones do these actions later after the workshop, to make sure the workshop remains a discussion space first.

Review questions and discussions topics

A Practice Review Workshop can combine both best practices and questions/topics submitted.
The purpose of questions/topics is to bring answers and discussions around a specific topic, which can then serve as a mean to create a new best practice. For instance, in this example, Bob has submitted a question on how to use logger to log errors. After some internal discussions, someone says a specific service should be used. And that's how you can create a best practice from questions!

Review existing practices

In case you still have some minutes for the Workshop, this last step invites your team to go through some existing practices from your space, that can you filter based on some conditions:
  • created a long time ago
  • most often identified as a counter-example for instance
The purpose is three-fold :
  1. 1.
    Keep your repository of best practices up to date, by stating together if they're still relevant or not.
  2. 2.
    Inform newcomers of some existing best practices they might not know yet.

Review other space practices

You can also identify practices recently created by other teams in other spaces, and retrieve them in your own space: