ah thanks! I was focusing on the template documentation because the revert was mentionned there. So I suppose that whole section should be removed, or linked to the one you linked about “volume backup and revert”
Those aren’t supposed to be instructions that a user follows to achieve some goal. Rather, that’s supposed to be a description of how the system is actually implemented.
User docs tell users how to do stuff.
Dev docs describe how the system works.
The suggestion that we should just drop the latter and link to the former in this case conflates these two types of documentation, overlooking their distinct purposes and natures.
But if there’s actually some content that’s outdated (e.g., a certain path or file no longer exists, perhaps because it has been has been moved, renamed, or replaced), then of course that should be updated.
This path at the end of the sentence doesn’t exist anymore, which makes the procedure unusable: Prepare snapshot device with root-cow.img.old instead of root-cow.img (/etc/xen/scripts/block-snapshot prepare).