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.
I remember coming across some sort of .go => .md generator in one of our Makefiles, (was it thumper’s pubsub?), but when I tried using it I couldn’t get it to work. I don’t remember the specifics as I didn’t try too hard. But that would give markdown for Github, and go pkg documentation for godoc.org.
I’m bumping this again, as I think we should at a very minimum add doc.go files to most if not all our worker packages. I believe that adding them although might slow juju velocity down to begin with, will decrease friction when it comes to having to work out roles and responsibilities of a worker, thus increasing juju velocity in the long run.
Please if you do edit or work on a worker package, take the time to add a doc.go file with at least some information about what it does, even if it’s just a short paraphrased few lines.
// Package containerbroker worker sole responsibility is to manage the lifecycle
// of a instance-broker. Configuration of the instance-broker relies on talking
// to the provisioner to ensure that we correctly configure the correct
// availability zones. Failure to do so, will result in an error.
//
// The instance-broker is created for LXD types only and any other container
// types cause the worker to uninstall itself.
package containerbroker
We have some docs in juju/doc as txt files. Let’s (I will) move those to the appropriate locations and transform them as doc-*.go files. They can be updated as people make changes.
Thinking out loud, but we could potentially go generate doc.go files from Discourse posts. We could have developer-centric documentation hosted on Discourse, with some conventions about what gets ported across to the package
Over time, we could create a developer guide for Juju’s internals.