@tess we do think you're right about this

we have friends who've chosen to approach this from the documentation angle (cf. https://www.kickstarter.com/projects/essential-randomness/the-fujoshi-guide-to-web-development/description ) and we do hope that will help

but it sure would be nice if the core git people would, like, loop in a tech writer for advice on names and conceptual organization and then actually take their advice