README is incomprehensible

[dsyer]

I found out by trial and error that if I want to use Java I can pass a build plan like this in stdout from a detect in another buildpack:

[openjdk-jdk]
  provider = ""
  version = "1.*"

I don't really know how or why that works. It would be kind of useful to get more detail and the README seems like an excellent place to start.

[nebhale]

@dsyer The README can obviously use some improvement, but what about the Build section didn't indicate to you that adding [openjdk-jdk] to the build plan would "Contributes a JDK to a cache layer". Just trying to determine why trial and error was necessary when that doc was in place.

[dsyer]

It doesn't say that [openjdk-jdk] is a line in the build plan (aka stdin). Also doesn't mention either "provider" or "version" or how they might need to be matched.

It's just not very friendly to someone who doesn't know the guts of buildpacks. Example

Contributes JAVA_HOME configured to a cache layer named the same as the key

• "Contributes" how? I assume it's an env var. Is it consumable by other buildpacks?
• "Configured to" do something or to be something? And what?
• What is "named the same as the key"?
• What's "the key"?

Examples are really useful for this kind of thing.

[nebhale]

Sounds good. We'll roll that input back into the docs.