I think this is fine, and it is great that the issue got resolved very quickly. However, I would like to drop a note that restraint needs to be applied when using Warning and other other admonitions.

Sure, when you are thinking of a particular situation, you want to make it stand out from the rest, with big red text and and a frame around the notice. However, many more people will be reading the same section, looking for something else entirely. For them, having the prose interrupted by admonitions is just clutter and distraction. So in my opinion, in almost all cases, it is better to add warnings and such as normal sentences.

(It would help if the stylesheet would not reserve the whole line for the admonition, but place it in the side. Maybe that could be taken up with the Docs team and stylesheet authors.)

Sure, admonitions shouldn't be overused, but they also shouldn't be avoided. So I don't agree with "in almost all cases, it is better to add warnings and such as normal sentences.".

Documentation is really not meant to be a continuous prose (unless it's a walk through or a tutorial). Most people rarely read a whole page from top to bottom. What they want is to be able to get maximum information by spending minimum amount of time---reading the least amount of text.

In this scenario, for example, someone would come looking to learn how they can untag a build from a side tag and very likely find the commands and stop there because the commands stand out. If the warning was merely a sentence, it wouldn't stand out, and they may miss it entirely and end up with the situation that this PR helps to fix. What would be more frustrating for them would be to later learn (or be pointed out) that this issue is "mentioned in the docs" but that they missed it.

So, let's use admonitions (and other formatting that helps people find information more efficiently) when they're appropriate and neither overuse nor avoid them.

The problem is, while you help some user who needs that information, you are distracting another user who would need some other information. For instance, just before the new Warning there is another sentence in normal type:

If you add or remove a build from a side tag, you will have to refresh the corresponding update in Bodhi.

Having a big red box right next to that important note makes it more difficult to spot it, and I do not really see why one of these items was chosen as the more important one.

In my opinion, it is better to organize text better and remove unneeded information, than try to raise individual items above the rest.

An example of that I consider appropriate use of adminitions: If side tag behavior is considered complex enough so that packagers need to be warned about them (I agree on this part), the following catch-all warning could be placed right in the beginning of Multi-package updates top level section:

WARNING

Multi-package updates are an expert topic. Side-tags and other tools used to manage multi-package updates are complex and their behavior is can be surprising. Take your time to understand the tools and their interaction with other parts of the build systems before performing any actions.

Because this is in the beginning of a top level section, it does not interrupt the flow of the documentation, and does suffer from the "why this, but not that?" problem.

Having a big red box right next to that important note makes it more difficult to spot it, and I do not really see why one of these items was chosen as the more important one.

A side tag going missing when builds are untagged is more of an issue and is more likely to happen in normal workflow than for folks to already push updates and then modify the side-tag, which is not part of the normal workflow. Instead of relegating the warning to normal text, perhaps the other note should be elevated and included in the warning too.

(I didn't even know that one could edit a side tag after a bodhi update was pushed---I thought the update being pushed meant the side tag was "done with". This is also what the docs sort of suggest: "When you’re done building all packages you want in a side tag, you have to submit them as an update to Bodhi before they can be made available generally to be installed and built upon." ).

the following catch-all warning could be placed right in the beginning of Multi-package updates top level section:

But this basically says "read the whole page carefully" and doesn't really add much information value to the page. It doesn't highlight any information as important, just says "everything is important".

As I've argued before---not all pages need to be read from start to finish and so have a flow. The walkthroughs in the docs are pages people should read from start to finish because they describe the whole process in a step by step fashion. They require a flow. Other pages like this one are not walkthroughs, they are references that people want to go to when they need to carry out a specific task. Having to read a whole page only to figure out how to tag/untag a build from a side tag is not efficient.

It's been ages since I read either the guidelines or the package maintainer docs, or any of their pages, from top to bottom. The most common use case for me is "how do I do this?" or "what do the guidelines say about this?", and then go and use the search function to arrive directly at the information I need.

How does #139 look as a sort of middle ground? It sill uses an admon, but makes it collapsible. So people are now made aware that "modifying builds in side tags can have unintended consequences" and those that may be doing this can expand to see details. It takes less space on the page too.

(My only issue with this is that my mouse doesn't change when I hover over the bit to expand the collapsible---so it isn't immediately clear that one can click to expand it).