improving intro and scopes doc