Excuse me if I plagiarize someone’s comment in this post, I can’t quote everything I’m trying to write this fast LOL cause I’m in the middle of something else...
Docs should be produced like any other publication, with a clear organizational structure, consistent tone/formatting/style. From my modest experience that looks like: Publisher, Editor-In-Chief, Department Editors, Technical Advisors, Staff Writers (usually in charge of specific sections/topics), Contributors, etc AND a "Style Guide" of sorts.
Obviously MODX does not have something like this in place, and no funds to do all this hiring, so we look to the community to provide a substitution but right now there’s no organization. SO...
I propose we "assign" a community volunteer to "fill" these positions for EACH snippet that gets approved for the repository. This may sound like a lot, but one person does the job for all, or a whole bunch, of the snippets. For example:
Publisher » @modxcms (if that wasn’t obvious)
Editor-In-Chief » Similar to Head of Documentation for WP. This person does at least one review on EVERY piece of documentation to ensure it meets some minimum requirements (set out in the Guide - more on that later). This person (if not one of core team) may need compensation of some kind - nice little write-up on modx.com, maybe an honorarium, etc cuz it’s a MASSIVE job.
Department Editors » In charge of whole groups of snippets. Can be categorized like the repo itself: "Content" section, "Navigation" section, etc. They will review and proofread EVERY piece of documentation for their group of snippets, edit, make changes, add stuff, make sure it’s well written and easily understood. They should have a pretty good understanding of their snippets but MORE IMPORTANTLY know how to deliver information in a useful and easy to understand way. Depending on how many snippets they’re in charge of this could be a small endeavour to a really big one.
Technical Advisors » Experienced MODX developers that the Editors above can depend on for help with their group of snippets, and who are able to write the "first pass" of most snippets. For MODX I see this group AND "Staff Writers" kind of being one and the same because the first pass at docs MUST be written by someone who knows very well how it works, obviously. A snippet’s dev - if they cannot even come up with a "summary" or a first draft - should at the VERY LEAST be able to explain it to a Technical Advisor who will write the first draft. Then NOTHING gets passed into repository without someone writing something!! After that, the Editors get it in their queue and when they get to it, they make it more user-friendly, if required.
Contributors » Anyone and everyone who’s willing to help but they MUST have some direction from the Editors in order for the docs to be consistent with the Guide.
No matter how we do it the Docs need a lot of work, but without organizational structure it will be for naught because it will never be consistent. If we want to expand MODX’s market to progressively less technical people (Techie designers»Non-technical designers»Hobbyists»End Users) then how far we can reach down that chain has everything to do with the Docs (and the Manager UI).
Just my 2 cents