-----BEGIN PGP SIGNED MESSAGE-----
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
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.
-----BEGIN PGP SIGNATURE-----
-----END PGP SIGNATURE-----