There has been some discussion about improving the internal documentation with in juju, so that understanding the code from someone developing has a better on boarding experience. It’s in our collective best interest to get people up to speed, rather than apply Cunningham’s Law to certain areas of the code base.
The general idea I want to propose is the addition of README.md documents with in packages. We get rendering of markdown documents for free in github (see https://github.com/juju/juju/tree/develop/acceptancetests as an example). The documents can cement what’s the purpose of a package, what is expected (tests, gotchas etc) and more importantly why somethings are implemented, so people can reason about the code. I’m thinking of the API backwards compatibility here…
If people are receptive to this idea (or suggest a better one than this), I think it would be great if people can start adding them in the future - note: I’m not expecting essays, bullet points with a small paragraph could suffice; just that it’s better to start somewhere than not at all.
Note: this is analogous Newcomer papercuts