improving documentation regarding events