[DOCS-1166][DOCS-880][DOCS-1167][DOCS-1168] Automation updates part 1 of 2 #1084
Conversation
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Deploying docs with
|
| Latest commit: |
5e032a0
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://8e5a6719.docodile.pages.dev |
| Branch Preview URL: | https://automation-updates.docodile.pages.dev |
Co-authored-by: Stephen Sisk <ssisk@users.noreply.github.com>
There was a problem hiding this comment.
A few high level thoughts:
- For any numbered workflows describing steps in the UI I think it is valuable to have a gif that corresponds to whatever steps we are trying to show
- The main thing I was hoping to address in this rewrite based on user feedback we got was to reduce the length of the one landing page. It's extremely long and overwhelming to find what you need to find. I think we should structure the automations section into several sub-sections, each a job to be done or a concrete workflow a user might come in trying to understand how to do it from start to finish. Right now it looks like everything is piled into _index which is super long and the user doesn't know what actions (i.e "how to troubleshoot your webhook endpoint") they can find in this doc.
There was a problem hiding this comment.
- Let's hold off on generating gifs yet. A gif, especially an animated one, suffers from technical debt each time we update the UI, even a minor update,. Also, images are large compared to paragraphs and can make the words seem less legible / can increase the cognitive load of reading the page. First I'd like to make sure that the words are as understandable as possible.
- Done! We now have a landing page, an "Event scopes" reference page, a "Create automations" landing page, and specific pages each for Slack and webhook. I left the example payloads and troubleshooting details in the webhook creation page to try to keep the whole task together. I also removed the previous model-registry-automations and project-scoped-automations pages again, which crept back into this PR somehow.
PTAL!
| 1. Click **Test** to test the webhook. Optionally, provide a payload to test. To refer to a secret the webhook has access to in the payload, prefix its name with `$`. Any payload you specify in this step does not persist, but allows you to test authentication. You configure an automation's payload when you [create the automation]({{< relref "#create-webhook-automation" >}}). | ||
|
|
||
| {{% alert %}} | ||
| See [Troubleshoot your webhook]({{< relref "#troubleshoot-your-webhook" >}}) to view where the secret and access token are specified in |
There was a problem hiding this comment.
I think users would find it helpful to see the webhook structure actually in this section as well, as they are in the process of constructing it. Again, I think have a whole section just on creating a webhook, just as you had done in here for secrets would be beneficial.
https://www.notion.so/wandbai/W-B-Post-Request-Structure-1a7e2f5c7ef380a6a446fce56201b00c?pvs=4 - we can include this structure information as well to help users as they are creating it (that doc is just an idea for how to explain the structure, we don't have to use that text exactly).
There was a problem hiding this comment.
Here is how product board shows the request structure in their developer docs - https://developer.productboard.com/reference/postwebhook-1
There was a problem hiding this comment.
I think this is more relevant to the automation API docs than for the guide about creating webhooks. The new webhook page includes the examples and the troubleshooting content. The API updates are a separate effort that is not in scope for this PR.
|
|
||
| ### Example webhook payloads | ||
|
|
||
| The following tabs demonstrate example payloads based on common use cases. Within the examples they reference the following keys to refer to condition objects in the payload parameters: |
There was a problem hiding this comment.
There is a also a metadata template string that is not in this list that we should add
There was a problem hiding this comment.
Thanks. Where can I learn more about it?
| Now you can [create a webhook automation]({{< relref "#create-webhook-automation" >}}). | ||
|
|
||
| #### Create the automation {#create-webhook-automation} | ||
| 1. Log in to W&B and go to the project page. |
There was a problem hiding this comment.
Hmm so here is where the nuance of the scope matters. The most common workflow is for users to navigate to a registry and create an automation in there. The instruction defined above is only relevant if you want to create an automation inside a project. And in registry, an automation can either be at the collection or registry level (i.e applies to all collection in a registry) - I think we would want a separate sub-page on the scopes available and how to create an automation for each.
There was a problem hiding this comment.
PTAL, I have now structured the Project and Registry tasks into tabs, filled in missing details about both registry collections and project collections, and expanded the Events and Scopes page.
Co-authored-by: Noa <40642416+noaleetz@users.noreply.github.com>
Co-authored-by: Noa <40642416+noaleetz@users.noreply.github.com>
- Use tabs for registry and project instructions - Add way more details about collection automations - Expand the Events and Scopes page and add a level of headings
Update all possible links and references to old Model Registry
Consolidate project-scoped and model registry automations, new Slack notification flow, add redirects
Out of scope:
In technical review
Preview links for major changes: