Documentation team, assemble!

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA512 Hey, So, I have also been thinking about a few things @nqb mentioned on the meet. I'm happy we care about a lot of the same stuff, so I thought I'd invite some structured discussion on a few issues. Also this touches on what @drybjed just posted on the project development model, but I'll try to keep this about doc and post that stuff there. # Documented means explicit Maybe I'm hammering on this one too often, but `parse_kv_config` has unit tests, excellent coverage, is totally required to understand debops, and it's only presented as an implementation detail on each role. It has all of the overhead of a promise to the end user, only missing the part where we make that promise. No action required, I'm handling this one, I'm just mentioning it as an example. As the project is facing the challenge of decentralizing responsibility, a whole set of guidelines need to be made explicit so they can be discussed and enforced without necessarily involving Maciej. It might be tempting to have him document everything every time there's an issue but there must be a better way! # Doc team. STYLE FORCE? Keeping the top-level doc consistent is not a task that will occur naturally as devs write roles. It involves keeping track of the onboarding path of all (or some) of the supported user types (say admin/user/dev), possibly presenting simplified versions to some. This mindset can be incompatible with someone who just explained a subject fully to the computer. I propose a documentation team, as I think it's not only a good responsibility to decentralize, but also a domain that could benefit from a perspective that's not the code author's. In broad strokes, the process I have in mind is like this: * Doc team gets `/docs` in `CODEOWNERS`, either wholesale or in chunks * Require a doc team member to close issues that add global functionality (No need to block the PRs themselves) * Leave the issue open and tag someone responsible if replies to an issue should result in documentation This doesn't apply equally to roles, since their actual codeowners will know the internal workings better, but the doc team will still be in the position to define and advocate for best practices. Obviously I'm not suggesting we write people's role doc. :D So the doc team turns answers into guidelines, helps people adhere to those guidelines, identifies unclear points and iterates. It might make sense to generalize the group's function to coding style as well, since those issues are likely to benefit from the same process. I'm not happy about bloating the group's responsibilities, but then it can be called `STYLE FORCE!`. xD I think that following such a convention would allow people to contribute to the project earlier and stay involved until they're ready to handle harder stuff. Even going from "I fixed some typos" to "I wrote an extra page" can be intimidating. Anyway, that's my RFC. I'd rather not be the team alone; I'm not even remotely financially secure to be able to solo such a commitment. If we're 2 or 3 people I can see it working, though. Tasos