provision documentation issue: on_failure spec missing

[mildwonkey]

Problem statement: I need to refer to older versions of the provisioner page to get the specification for on_failure.

Old page:

---

Current (latest) page:

---

The latest page now includes a link to the resource block spec, which also doesn't include the allowed values for on_failure:

---

The specific request here is that we get the allowed values for on_failure documented, but I have more overall concerns about the changes to the provisioners page. I'm genuinely concerned there was some confusion and the documentation was replaced with more tutorial-style copy.
That's visible even in the page title: the heading "Perform post-apply operations" instead of the original "Provisioners" title.

Also the "Provisioners are a last resort" section is INCREDIBLY IMPORTANT and SHOULD NOT BE REMOVED and should remain at the top of the provisioners documentation - we refer back to that constantly. It needs to be at the top of the provisioner documentation. We don't want to encourage users to use provisioners if there is any other method available.

I can to open a PR reverting this page page to it's last good version, which seemed to be around 1.10, but that seemed kind of passive aggressive, and doesn't help with the other pages we're finding missing information on.

[trujillo-adam]

Thanks for flagging this. I re-added the missing on_failure reference information. When the site finishes redeploying, the link on the page you mentioned goes to the spec: https://developer.hashicorp.com/terraform/language/block/resource#on_failure

Regarding your concern about making sure people understand that provisioners are an anti-pattern, there is a hard-to-miss warning about provisioners in the reference page:
https://developer.hashicorp.com/terraform/language/block/resource#provisioner

Should we also add the warning to the usage page where we first introduce provisioners? https://developer.hashicorp.com/terraform/language/provisioners

Regarding the page title and change in how we're presenting the information, we think that the job practitioners want to do is prepare resources for service after applying the configuration and not necessarily how to use provisioners. We are also implementing diataxis as our primary organizing principle. The previous version of the page was a mixture of reference and how-to information. The page is now a how-to that links to the reference docs. We think that this standardized approach will help users consume the information and help us maintain it over time.