https://issues.redhat.com/browse/ACM-13324 #7246
Conversation
| [#prevent-backup-collision] | ||
| == Preventing backup collisions | ||
|
|
||
| To prevent and report backup collisions, a `BackupCollision` state exists for the `BackupSchedule.cluster.open-cluster-management.io` resource. The controller checks regularly if the latest backup in the storage location has been generated from the current hub cluster. If not, a different hub cluster has recently written backup data to the storage location, indicating that the hub cluster is colliding with a different hub cluster. |
There was a problem hiding this comment.
To prevent and report backup collisions, a BackupCollision state exists for the BackupSchedule.cluster.open-cluster-management.io resource.
This line is confusing, I think the word exists here and To prevent.....
I think rearrage this just to say X does Y??
|
|
||
| To prevent and report backup collisions, a `BackupCollision` state exists for the `BackupSchedule.cluster.open-cluster-management.io` resource. The controller checks regularly if the latest backup in the storage location has been generated from the current hub cluster. If not, a different hub cluster has recently written backup data to the storage location, indicating that the hub cluster is colliding with a different hub cluster. | ||
|
|
||
| In this case, the current hub cluster `BackupSchedule.cluster.open-cluster-management.io` resource status is set to `BackupCollision` and the `Schedule.velero.io` resources created by this resource are deleted to prevent data corruption. The `BackupCollision` is reported by the backup policy. The administrator verifies which hub cluster writes to the storage location, before removing the `BackupSchedule.cluster.open-cluster-management.io` resource from the invalid hub cluster and creating a new `BackupSchedule.cluster.open-cluster-management.io` resource on the valid primary hub cluster, to resume the backup. |
There was a problem hiding this comment.
In all of the tech writing, please look at words like "in this case" and look to eliminate it as not concise or extra words. I also think this is another example of a wall of text and needs to be reduced/reorganized a bit. I will leave that to you since we have gone through an exercise or two of that.
|
|
||
| To prevent and report backup collisions, use the `BackupCollision` state in the `BackupSchedule.cluster.open-cluster-management.io` resource. The controller checks regularly if the latest backup in the storage location has been generated from the current hub cluster. If not, a different hub cluster has recently written backup data to the storage location, indicating that the hub cluster is colliding with a different hub cluster. | ||
|
|
||
| In the backup collision scenario, the current hub cluster `BackupSchedule.cluster.open-cluster-management.io` resource status is set to `BackupCollision`. To prevent data corruption, this resource deletes the `Schedule.velero.io` resources. The backup policy reports the `BackupCollision`. In this same scenario, the administrator verifies which hub cluster writes to the storage location. The administrator does this verification before removing the `BackupSchedule.cluster.open-cluster-management.io` resource from the invalid hub cluster and creating a new `BackupSchedule.cluster.open-cluster-management.io` resource on the valid primary hub cluster, resuming the backup. |
There was a problem hiding this comment.
This paragraph is a little long, I'd recommend breaking it up
There was a problem hiding this comment.
@oafischer please see Dev feedback asking to keep it as one paragraph.
I'm happy to tighten it sentence by sentence, but I was requested to keep it as one paragraph as a way to maintain user focus and understanding.
There was a problem hiding this comment.
I'd suggest separating it anyway, we've gotten customer feedback about reducing walls of text. I'll leave the final decision up to you but I'd argue that the customer feedback takes priority. We can look at connecting both paragraphs better with other writing methods, if necessary.
There was a problem hiding this comment.
I agree with @oafischer and we have feedback to "avoid walls of text" that I have shared in our doc meetings. As the writer, we take authority of the UX of the doc and find a way to make the paragraph concise without losing meaning. I can help with another exercise if that will be beneficial. I can tell by looking at it that we can break it up and remove some unnecessary words for better UX. Let me know if you would like to go over this.
There was a problem hiding this comment.
@swopebe Hi, thanks for you input.
Yes, I'm aware of the "walls of text" that you discussed in meetings. And yes, I'm aware that as the writer, we take authority of the UX. As you'll see in Sahar's comment, her criticism is that understanding was lost and the user would be lost. Your criticism was that the content was long. Therefore, taking ownership of the content, I prioritized the feedback that said the content was unclear and that the situation wasn't adequately described. With that said, I did still implement feedback of yours like when you said to remove the phrase "in this case" and shorten the sentences.
This PR is an example in which I was asked to do two different, contrasting things by the peer reviewers and I think, I found a good middle ground which still addressed your primary concern of shortening the content and fixing the headings and organization.
Also, I agree this paragraph is a little on the long side, especially the last sentence. However, it was 5 sentences and 88 words, neither of which are considered overly long from a documentation standpoint. As the tech writer of this content, the SME told me the situation wasn't described clearly enough. Applying this feedback, I wrote a sort paragraph of less than 100 words which the SME approved, so I actually wouldn't consider this to be an egregious example of "wall of text"
Nevertheless, I made another commit. Let me know what you think.
There was a problem hiding this comment.
I think the separation you provided makes sense and is much needed.
|
|
||
| To prevent and report backup collisions, use the `BackupCollision` state in the `BackupSchedule.cluster.open-cluster-management.io` resource. The controller checks regularly if the latest backup in the storage location has been generated from the current hub cluster. If not, a different hub cluster has recently written backup data to the storage location, indicating that the hub cluster is colliding with a different hub cluster. | ||
|
|
||
| In the backup collision scenario, the current hub cluster `BackupSchedule.cluster.open-cluster-management.io` resource status is set to `BackupCollision`. To prevent data corruption, this resource deletes the `Schedule.velero.io` resources. The backup policy reports the `BackupCollision`. In this same scenario, the administrator verifies which hub cluster writes to the storage location. The administrator does this verification before removing the `BackupSchedule.cluster.open-cluster-management.io` resource from the invalid hub cluster and creating a new `BackupSchedule.cluster.open-cluster-management.io` resource on the valid primary hub cluster, resuming the backup. |
There was a problem hiding this comment.
I agree with @oafischer and we have feedback to "avoid walls of text" that I have shared in our doc meetings. As the writer, we take authority of the UX of the doc and find a way to make the paragraph concise without losing meaning. I can help with another exercise if that will be beneficial. I can tell by looking at it that we can break it up and remove some unnecessary words for better UX. Let me know if you would like to go over this.
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: jc-berger, sahare, swopebe The full list of commands accepted by this bot can be found here.
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
See Jira: https://issues.redhat.com/browse/ACM-13324