David Bustos wrote: > Quoth Alan Maguire on Thu, Jan 10, 2008 at 09:41:35AM +0000: >> "For the currently selected instance, update the running configuration >> snapshot with the values from the current configuration. If the currently >> selected repository is being monitored, the service's restarter will be >> informed of the change, and if this restarter is svc.startd(1M), the refresh >> method will be invoked (if it exists) to request the service reread its own >> configuration. For other restarters, see the restarter documentation." > > Good, though I think you should add "by svc.startd" after "monitored". > I also can't decide whether mentioning svc.startd's refresh method here > is too verbose, and we should just instruct reading the restarter's > documentation. Take your pick. > >> it's based mostly on the language in "svcadm refresh", combined with >> most of your suggestions. i'm a bit wary of introducing new words >> like "commit" though, as they might suggest there's a new or different >> concept in play with the svccfg refresh subcommand. let me know what >> you think. > > I understand your hesitation, but I think we often do a significant > portion of users a disservice by choosing more precise but more > sophisticated language over simpler language. I'm usually out of sync > with the rest of the team on these issues, though, so go ahead and opt > for precision.
Hmm, not really out of sync with the rest of the team. I agree we do everyone a disservice when we choose unhelpful precision over simple statements. I had suggested two alternatives to Alan, including one with less precision in favor of simpler words we present more frequently to users, which you rejected because it wasn't really precise enough. :) This is getting far more precise than the previous formulation, and is getting less clear to me. Especially the part about "currently selected repository is being monitored by svc.startd". I'd really prefer something that helps the user based on how they got in the situation rather than helps them based on how the system is behaving. That is, tells them that the snapshot is updated, and if you didn't use the "repository" subcommand, refresh method will be called, perhaps tells them other restarters may act differently. Would that be ok? liane
