README in packages

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

4 Likes

+1 from me.

One of the things that would aid me as a newcomer to the project would be if packages could include:

  • “local expert” - is there a goto person who knows this code best?
  • “is it current best practice?” - are the practices that this (sub)package uses
  • “where did it come from?” - could we link to notes anywhere? sprint minutes? (although I guess this wouldn’t be available publicly)

Rather than a README file, how about a reaonble doc.go that has package documentation.

Then anyone going to godoc.org can see them.

I’m totally open to the godoc! As always we can always experiment, nothing is set in stone!
Any ideas of good places to start @thumper?

We already have a number of packages that have a doc.go file.

I suggest we just move forwards with documenting the packages as we go.

1 Like

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.

1 Like

Seems like Dave Cheney has something around this, but looks like it’s quite old, might be worth bringing up to date.

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.


Example of a new doc.go for the container broker.

// 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
2 Likes

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.

Hey @simonrichardson thanks for bumping this.

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.

1 Like

Sidenote: we please move this thread to #devel?