docs: some small changes to retries docs

Signed-off-by: blam <ben@blam.sh>

docs/features/software-templates/experimental.md

@@ -13,15 +13,15 @@ Please leave feedback on these features in the [Backstage Discord](https://disco
 
 ## Retries and Recovery
 
-Do you have long-running tasks, and can they recover and proceed after Backstage redeploy?
+Running tasks, especially longer running ones can be at risk of being lost when the `scaffolder-backend` plugin is redeployed. These tasks will just be stuck in a `processing` state, with no real way to recover them.
 
-Then you will definitely benefit from enabling the experimental recovery feature for scaffolder tasks.
+The experiemental Retries and Recovery is here to help mitigate this.
 
-Whenever you do redeploy, on startup there will be a check of all tasks in "processing" state that you identified in your template as being capable of starting over.
+Whenever you do redeploy, on startup there will be a check of all tasks in `processing` state that you identified in your template as being capable of starting over.
 
-More details about the motivation and the goals of this feature can be found in [the "Scaffolder Retries and Idempotency" BEP](https://github.com/backstage/backstage/tree/master/beps/0004-scaffolder-task-idempotency)
+More details about the motivation and the goals of this feature can be found in [the `Scaffolder Retries and Idempotency` BEP](https://github.com/backstage/backstage/tree/master/beps/0004-scaffolder-task-idempotency)
 
-This is an example of how you can enable this in your Template entity declaration:
+Here is an example of how you can enable this in your `template.yaml` manifest:
 
 ```yaml
 apiVersion: scaffolder.backstage.io/v1beta3
@@ -33,39 +33,34 @@ spec:
     EXPERIMENTAL_strategy: startOver
 ```
 
-To enable the recovery feature, add this snippet into your app-config.yaml file:
+You'll also need enable the recovery feature, add this snippet into your `app-config.yaml` file:
 
 ```yaml
 scaffolder:
   EXPERIMENTAL_recoverTasks: true
 ```
 
-By default, the tasks that are in a processing state and have a heartbeat of more than 30 seconds will be automatically recovered.
-This implies that the task's status will shift to "Open," initiating its execution from the beginning. So you have to be sure that your tasks can run multiple times.
+By default, the tasks that are in a `processing` state and have not reported back with a heartbeat for longer than 30 seconds will be automatically recovered.
 
-![Task recovery visualization](./task-recovery-visualisation.png)
+This implies that the task's status will shift to `open` initiating and will be restarted from the beginning. This means that it's important that your actions that you have in the template run are idemopotent.
 
 You can look at how to incorporate [checkpoints](https://backstage.io/docs/features/software-templates/writing-custom-actions#using-checkpoints-in-custom-actions-experimental) into your custom actions to achieve that.
 
-In case 30 seconds of no heartbeat time is not appropriate for your case to restart the task, you can customize it for your needs with the configuration:
+In the case that you would like to make the heartbeat threshold shorter or longer than the default 30 seconds, you can customize it for your needs with the configuration:
 
 ```yaml
 scaffolder:
   EXPERIMENTAL_recoverTasksTimeout: { minutes: 1 }
 ```
 
-If your task works with the filesystem, you might require serialization of your workspace.
-
-You can enable this feature with:
+If your task works with the filesystem and stores files in the workspace and you want to store these workspaces across runs, you can enable this with some additional config to `app-config.yaml`
 
 ```yaml
 scaffolder:
   EXPERIMENTAL_workspaceSerialization: true
 ```
 
-By default, the serialized workspace will be stored in your database.
-
-If you work with large files, it might not be the best option for you.
+By default, the serialized workspace will be stored in the database, however if there's larger files, or if you're worried about the size of these files taking up space in the database you can configure bucket storage and have a sensible retention policy there to cleanup older files.
 
 At the moment we also support integration with Google GCS; to switch the serialization to this provider, you can do so with: