Resolve #549 Document Long and short cache
Created by: seamuslee001
@MegaphoneJon @eileenmcnaughton @totten
I have included in this PR the commits from #639 as i think it makes more sense to document that and this together but this primarily is about the new paragraph doucmenting the long and short caches. What i don't have here is why someone would use a long v short cache but perhaps that will be fleshed out in review