updated doc based on feedback (redmine #14633)