Docs: Split email notifications and webhook notifications into separate howtos #10396
Conversation
docs/user/guides/build/webhooks.rst
Outdated
| @@ -80,7 +61,7 @@ you will see the server response, the webhook request, and the payload. | |||
| Activity of a webhook | |||
|
|
|||
| Custom payload examples | |||
| ~~~~~~~~~~~~~~~~~~~~~~~ | |||
| ----------------------- | |||
There was a problem hiding this comment.
I think we shouldn't change these here. ~~~~ are used as subsections of Build status webhooks and I think it's correct to be subsections.
There was a problem hiding this comment.
I reverted it 👍
But essentially, it's because I wanted to go towards a step-wise how-to (and not nested sections like we have in reference or explanation). Unfortunately, this how-to is very far from such a result :)
In general, how-tos are better like....
Do this
-------
lorem ipsum
Then do this
------------
lorem ipsum
There was a problem hiding this comment.
The following two were not updated and they should because of the same reason.
I understand what you want to achieve with the sections, but this case doesn't work like that since they are subsections and not steps the user has to follow.
| Build Notifications and Webhooks | ||
| ================================ | ||
| Build notifications via webhooks and email | ||
| ========================================== |
There was a problem hiding this comment.
re: naming is hard
I changed the feature page to have this title instead. I think it's clearer than the previous one.
I think we should try to use:
- "Email notifications" when it's the feature in particular and when we want to have a short and sweet name
- "Build notifications [via webhooks/email]" when we are talking about the value of having instant build feedback more broadly. It's also really good to say "build notifications via webhook" rather than just "webhooks" since the latter can already mean 3 different types of webhooks... incoming (our API), outgoing (GitHub's API) and build notifications (calling other webhooks with payload templates).
Oh yes, and of course we also say "build status webhooks" 🙃 Not on the website, it just says "webhooks" :)
We could remove "build status webhooks" and say "build notifications via webhooks" or "notification webhooks". It's not any big thing, though, anything containing the word "webhook" is bound to be a bit technical :)
| How to setup build notifications and webhooks | ||
| ============================================= | ||
| How to setup build status webhooks | ||
| ================================== |
There was a problem hiding this comment.
I guess we should be systematic about calling the feature "build status webhooks" since that's how it is right now.
If we're gonna do anything more drastic, I think it should include the Dashboard terminology, so I would just save that for later..
| .. note:: | ||
| Read the Docs can notify external :term:`webhooks <webhook>` when builds are triggered, successful or failed. | ||
| In that way, | ||
| you can receive build notifications in your own monitoring channels and be alerted you when your builds fail so you can take immediate action. |
This splits existing howtos into two separate articles:
Very little text editingEditing a lot of the texts for clarity and smoothnessRefs: #9747
📚 Documentation previews 📚
docs): https://docs--10396.org.readthedocs.build/en/10396/dev): https://dev--10396.org.readthedocs.build/en/10396/