-----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
-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEXbaOHtREtFSBLXcdOXguVye2c7EFAl8ZbEQACgkQOXguVye2
c7G38hAAhPFStDkNfTf57q8Ta4EEjEIXlyR8gcZTCr4RG3sCW3Lvy+EpHVwTh7YP
YqBrHKS83yRFld0xLEjRN0d7SiUlJCMWG93zY7qCRysU/CvFQYQftFsbHlekWRqk
tECFHadaRQ4/GJr1BSHkgrjRBqvVIsg0JBh9JqyJC0Nso+Z4CqAvknRSXqgS6ytb
FeWrqMSy8Q8eCN5csjvs31+TVf6Vv+9+MffSuFNv2yDs0pwyOopNRhNAtwirOqdk
ys08orPbGCfugZLdnMBIARG3ROpnPSPIEoK9Wkm0XVskxZI5YByVg4rtEL6zYWBp
+Erzjgxc/1ryTh23q6gVZv8LAvxd01Z5zIcJg9snEEJFhLKd5E2GEB6lmH1D15nX
izSw7XDguDWNon7eWikakOs0+Y0BaBORilgmJgMisZOzgjcKU/htdtc8oQYTLaqy
mYQPOlXcH/R6HsdmNFficejZzH5oeqnYhNvN7qBoONCvTQDBX1+1CP5PQUbLUJ9U
ngg3M3cVvEhVPXp3AVLw6Gp9SJijpLK47JrZYOpCk9j5FSEpjO6J9E99WX4pQVI1
fvw2aCWmxwRxxgNqEZzmGCVYxj82kz5VnLWIEU8rc8fK1OudhQvZsS1yhENUKgZo
mbwuapqdjj3WAwJNvdXDGZhZiEyEN0oWUz6aMDeycjWEY7P2uyA=
=EY7U
-----END PGP SIGNATURE-----