I’m curious if anyone would like to share how they document their scenario specifications. I am going to be working with others and will need to have a solid way to capture requirements into a spec, and use it for both development and maintenance.
I have drawn up some guidelines for our scenarios.
The idea is that through clean and logical labelling the scenario does not need any further documentation.
Scenario Coding Guideline
First and foremost, the scenario should be understandable. To achieve this, a scenario may use more operations than absolutely necessary.
Set variable for complicated queries
Split several filters into two filters with the help of Router
The filter is always described for a router (even if no filter is set)
The description should explain when a process takes this route.
API or GraphQL modules must be renamed to their function via rename.
Modules that get, create or fetch an item must be titled with the logical item name.
Example: If an item is searched for in monday.com, then it should be written what kind of item is being searched for. (For example: project-item or linked board-item)
Code duplications should be prevented if possible
Outsourcing such as Http and Webhook can be used here
Rename http call to the scenario name of the webhook
Add note in make with scenario URL of webhook scenario
The use of error handlers should be avoided as far as possible during development. Every error should be checked and not simply routed to an error path
