The diatagix framework (https://diataxis.fr/) helps us with a description of a structure on what to document where. We are currently missing the explanation part, and I think we would benefit from it to offload other sections of the documentation.
For example, consider how to document the help string of OAuthenticator.authorize_url, OAuthenticator.userdata_url and OAuthenticator.token_url etc, it doesn't really make sense to do it in isolation, and neither does it make sense to do fully in either help strings. Instead what could make sense is to have a section explaining some OAuth stuff to the extent that we can just reference the explanation section that mentions these URLs.
The diatagix framework (https://diataxis.fr/) helps us with a description of a structure on what to document where. We are currently missing the explanation part, and I think we would benefit from it to offload other sections of the documentation.
For example, consider how to document the help string of
OAuthenticator.authorize_url,OAuthenticator.userdata_urlandOAuthenticator.token_urletc, it doesn't really make sense to do it in isolation, and neither does it make sense to do fully in either help strings. Instead what could make sense is to have a section explaining some OAuth stuff to the extent that we can just reference the explanation section that mentions these URLs.