One question is who would be allowed to setup Herald rules. Developers? Project maintainers? Only sysadmin / community admins?

Global Herald Rules can only be setup by members of the Community Admins project (sysadmins + select community members) at the moment.

Unfortunately it needs to be limited, as global rules can arbitrarily be used to add projects, subscribe people, remove people, etc which could be abused quite a bit (including to spam people).

Anyone will be able to setup personal rules - letting them subscribe / add themselves as a reviewer / etc to things that they're interested in. It's only things like sending to mailing lists (which needs a mailing list user anyway) which needs a global rule.

We would also use a global rule to trigger things like Jenkins builds from reviews when we implement that.

In theory you could copy / adapt Wikimedia's docs at
https://www.mediawiki.org/wiki/Phabricator/Help#Creating_Herald_rules_for_notifications
https://www.mediawiki.org/wiki/Phabricator/Help/Herald_Rules

We therefore need to write some documentation on this, and on how to setup rules.

Where should those docs be located preferably?

We've since had to restrict personal rule creation - as apparently too many Herald rules can adversely impact on the performance of Phabricator. This is especially problematic for Maniphest / Differential as those Herald rules are evaluated every time someone makes a change - with the performance impact being around 1ms/rule.

Several hundred rules is easily forseeable on an instance like our own with personal rules - something which could harm the experience quite a bit.

In terms of where docs should be located, I'm not sure. I guess they should probably go on the Community wiki?