better documentation around scope