Comment on page
How to run a Practice Review Workshop
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.
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:
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 :
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
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.
- 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.
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!
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.Keep your repository of best practices up to date, by stating together if they're still relevant or not.
- 2.Inform newcomers of some existing best practices they might not know yet.
You can also identify practices recently created by other teams in other spaces, and retrieve them in your own space: