Docs: Split "Automation rules" into reference and how-to (Diátaxis) #9953
Conversation
benjaoming
added
Improvement
docs/user/automation-rules.rst
Outdated
| When a new webhook event is received from your Git provider, | ||
| All rules with a successful match will have their action triggered in the order they appear on the :guilabel:`Automation Rules` page. |
There was a problem hiding this comment.
I need some feedback here. In a former section, we state:
When a rule matches a new version, (...)
We should be more specific about the trigger. What happens when a new rule is added for a tag or branch and then something new shows up? What happens when a Git tag is deleted and re-added?
| Want to test if your rule works? | ||
| You can test if your rule works in a few minutes without disturbing your readers: | ||
| If you are using Git tags in order to create new versions, | ||
| create a Git tag that matches the rule and check if your automation action is triggered. | ||
| After the experiment, | ||
| you can delete the Read the Docs version and the Git tag. |
There was a problem hiding this comment.
I find this tip to be useful, however I don't know if the process is the best way of testing a rule. Are there other ways of checking if a rule triggers?
…g into diataxis/split-automation-rules
|
Some attention to labels and help texts in the "Add rule" form could be nice, but I think we can skip the scope creep and consider this change separate from further improvements on the Dashboard. @ericholscher would you like to try to take over this PR instead of reviewing? Just add changes directly and LMK when it looks good to you? |
|
Also noteworthy: I left a slightly variating repetitions of content between how-to and reference that I thought was simply more useful for the reader than a cross-reference. |
ericholscher
requested review from
ericholscher
and removed request for
agjohnson
| @@ -0,0 +1,84 @@ | |||
| How to manage versions automatically | |||
| ==================================== | |||
There was a problem hiding this comment.
This title is great to improve with the user's problem in mind.
|
Ran out of time again today, keeping this for tomorrow. |
|
|
||
| Want to test if your rule works? | ||
| You can test if your rule works in a few minutes without disturbing your readers: | ||
| If you are using Git tags in order to create new versions, |
There was a problem hiding this comment.
I don't love this, but seems useful. A bit overly specific perhaps, and not always applicable?
| All rules are evaluated for this version, | ||
| in the order they are listed. | ||
| If the version **matches** the version type and the pattern in the rule, | ||
| the specified **action** is performed on that version. |
There was a problem hiding this comment.
A diagram would be great here in the future, but probably too much for this refactor.
There was a problem hiding this comment.
If we can establish a quick way to use Mermaid diagrams, this would definitely be a valid option. Last time, I hit some issues that would need to be solved, so ended up generating Mermaid.js and saving as PNG "by hand" which was a bit too cumbersome for a "quick diagram".
…g into diataxis/split-automation-rules
…ng/readthedocs.org into diataxis/split-automation-rules
| @@ -1,96 +1,110 @@ | |||
| Automation Rules | |||
| Automation rules | |||
There was a problem hiding this comment.
haha just read this again and realized that it sounds a lot like "automation rules [verb]"
Maybe that'll make people click it, anyways :)
|
Yes, I didn't find anything, but I've also looked at it too many times 🙃 |
Scope of work:
Reference: "Automation rules" need to have a clear and simple feature reference.
Explanation: New explanation contents can be avoided, since there is already an explanation article around versioning.
How-to: It would work well to have a How-to guide that can be referred to, similar to Redirects how-to, which lists out the concepts with hoverxref'ed links to their reference.
Tutorial: nay
New how-to: "How to create new versions automatically"
Refs: #9746
📚 Documentation previews 📚
docs): https://docs--9953.org.readthedocs.build/en/9953/dev): https://dev--9953.org.readthedocs.build/en/9953/