alerts: improved docs