Suggestion to make example docker README.md more intuitive

[flo-kn]

Attempt and suggestion to make this example more intuitive to reproduce with docker compose.

closes https://github.com/strimzi/strimzi-kafka-oauth/issues/237

[mstruk]

@scholzj is right. The problem is simply in that the particular README is actually confusing for the beginner about which should be the current directory where mvn build is run, and also where docker-compose commands are run. The instructions proposed here are not the way one should use this. But READMEs are indeed confusing in that there are too many of them, and the they contain partial information expecting the user to have started top down from examples/README.md to examples/docker/README.md to possibly the individual service examples/*/README.md for even more info. If starting from the bottom up a newbie user may not properly 'connect the dots'.

[flo-kn]

I'm not sure I follow this change and the error in the related issue. It seems you just didn't build the project first? Can you please elaborate more on it?

@scholzj Yes, certainly. Will try to answer both questions in one answer and try to relate to what @mstruk commented before: In short: Not 'connect the dots' is exactly what happened.

Coming to the repo as a generalist with some knowledge and experience around kafka, k8s, java, auth, github - but fairly new to strimiz and total newbie/beginner to strimzi-kafka-oauth, I think the docs on how to get started and get things up an running is not clear:

1. Scanning and scrolling down the root readme I arrived at the Building Heading. It comes after the theory/general explanation section suggests that the hands-on part will now start. However, before there is a link to the existing examples (Screenshot).
   Maybe it would be more intuitive to drag in another 1st Level-Heading, something like Getting Started and put the other headings (building, installing) underneath on 2nd level :

   Getting Started
   ---------------
   ### Building
   ### Installing

   

   Don't know. Not thought through of course. But just to elaborate a bit on the challenges I had to follow through.

2. mvn clean install That command is the only thing you get. Nothing mentioned about what it does, whether it is needed for running the examples. The Required Java-Version, other Prerequs what have been needed here from my perspective (That is mentioned in the HACKING.md). I think, at least some parts from HACKING.md could be move over to here, the parts to make work on a personal Dev Environment.

   @scholzj So I am indeed at this point now. Before, filing this PR, I tried to build from the root level of the repo, but was getting a compile error on my workstation from mvn clean install, probably from referencing a JAVA version different than 8. 🤷‍♂️ So instead I was following the flow of the examples readme trying to get at least the partial build right to make the example work for my purpose bottom up until the partial build worked. (Hope this long write-up is understandable )

Not sure if anything general can be derived from this, maybe for others familiar with the ecosystem everything is clear. Personally from my perspective a bit more getting started guidance from the docs would have been beneficial.

[scholzj]

@flo-kn Right. I'm not arguing that it was your fault or that the READMEs are all perfect. All I was trying to say is that I do not think you are supposed to add the 0.15.0 version into the pom.xml here.

• If you wanna use some particular released version such as 0.15.0, you should use the examples from the release tag
• If you want to use the latest development version, you need to build the project.

That is what I think we need to cover in the READMEs.

[flo-kn]

All I was trying to say is that I do not think you are supposed to add the 0.15.0 version into the pom.xml here.

Yes, thanks for the quick feedback and clarification. Appreciate it. 🫶

Suggesting to just close this PR.