some documentation updates in the FAQ vignette