Dave Hall via Mailman-users writes:
I have seen this with several open source projects lately. There's no big picture, just 'hundreds' of cross-linked little bits of disjointed information that almost seem like documentation for individual modules.
It is documentation for hundreds of individual modules. That's, like, the point of open source software. ;-)
So, a challenge for us all: When writing and reviewing your documentation, imagine that you're explaining your whole project face-to-face to your grandmother, or to anybody who never learned to program. From experience I promise that it's easy once you get the hang of it.
I agree in principle, and for greenfield projects I agree that many/most developers can get the hang of it and it's easy (fsvo "easy") once you do.
But in decades-old open source development projects at Mailman 3 scale (which isn't even all that big), most of is not our job. For example, the HAYSTACK_CONNECTION variable that incited this thread is buried deep in a Django extension that's distributed independently of Django. The best we can do with modules like that is cookbook explanations (I'm pretty sure there is at least one and likely two or more in the official docs on list.org or readthedocs). If the cookbook recipe doesn't work, I doubt anybody here can write anything deeper off the top of their head.