Add explanation/concept for extension maturity model

[holly-cummins]

This is part of the bigger plan for extension documentation: https://github.com/quarkusio/quarkus/issues/37288


Obviously, there’s a gap for dev services documentation, which I’ll move on to next. Once I've got something linkable for dev services documentation, I will come back and link here.

One of the links needs quarkiverse/quarkiverse#229 to merge for it to resolve. I decided to be optimistic about the order things would happen and put the link in anyway.

The preview comments aren't working, but this is the link to the new page: https://quarkus-pr-main-42446-preview.surge.sh/version/main/guides/extension-maturity-model

Question for reviewers: Should the list at the top be numbered? Or perhaps a graphic, so that it's more distinct from the table of contents lower down? https://en.m.wikipedia.org/wiki/File:Characteristics_of_Capability_Maturity_Model.svg is a somewhat standardised visualisation of maturity models, but it's harder to edit than raw text.

[quarkus-bot]

Status for workflow Quarkus CI

This is the status report for running Quarkus CI on commit 16e3f8e.

✅ The latest workflow run for the pull request has completed successfully.

It should be safe to merge provided you have a look at the other checks in the summary.

Warning

There are other workflow runs running, you probably need to wait for their status before merging.

You can consult the Develocity build scans.

[maxandersen]

good stuff! just suggestion on cleaner ordering

[gsmet]

I like the general idea.

I added some comments here and there.

[gsmet]

I think it needs to be clear that you don't need to implement all of this before releasing your extension. It's more or less mentioned but people have a tendency to go over the top sometimes when developing in the open and we need to clarify it's OK to publish a first version that doesn't handle everything.

[holly-cummins]

Yes, agree 100%. I was trying to convey that (and I think it's kind of implied by the maturity model), but I will be more explicit about that.

[holly-cummins]

The order in this model isn't exact. Different developers will have different views on what capabilities are most important. You may wish to (say) prioritise performance over enhancing your extension's Dev UI tile. That's fine!
Also, not every step will apply to every extension. For example, you don't need a dev service if your extension doesn't depend on external services.
It's completely OK to publish a first version of an extension that doesn't handle everything. In fact, it's ok if your extension never gets to the more advanced features. This is a suggested pathway, not a minimum feature set.

?

[gsmet]

Perfect! (sorry forgot about it!)

[holly-cummins]

I’ve changed the list to a graphic. This has the benefit of adding something beyond what’s in the ToC below and the base writing-extensions guide. It has the disadvantage it’s hard to maintain. I don’t have the tools to do it, but @insectengine might be able to convert it to an svg, which would still render nicely, but would have a slightly higher bus number than my png.

[github-actions]

🙈 The PR is closed and the preview is expired.

[insectengine]

Created a slightly different view of the graphic (PNG and .SVG)

[holly-cummins]

Created a slightly different view of the graphic (PNG and .SVG)

Thanks! Visually, that looks way better than mine, but I'm not sure about the shape. I think people's expectations of a maturity model would be a bit more stair-case-y. There's some variation in what google shows, including one pyramid, but almost all of them have a linear progression from bottom to top and left to right:

I had in mind something like this:

Because we have more stages than that example it does make it harder to fit everything on the page, but I think it does make it easier to understand the intent.

[insectengine]

posted PNG and SVG versions above. The difference between them is the alignment of the dotted line separator.

[holly-cummins]

I've incorporated @insectengine's much more attractive graphic. Preview link: ttps://quarkus-pr-main-42446-preview.surge.sh/version/main/guides/extension-maturity-matrix

Based on the conversation, I'm not aware of any blockers to merging at this stage.

[cescoffier]

Yes, all good for me. The new matrix looks great!

[maxandersen]

+1!

I would still go for removing the "progress line" as its not really a progres.

[cescoffier]

@holly-cummins do you think we can get the "dotted line" removed from the matrix?

[holly-cummins]

I wasn't super-wedded to the dotted line, so I asked James to do a version without the line. Buuut ...

... looking at the version without the line, I think it loses a surprising amount of meaning. Without the progress indicator, it looks a bit like a random collection of blobs, and there's no sense that people should be aiming to progress through them.

So now I'm back to thinking we should stick with the dotted line.

[maxandersen]

I grok why you feel something is missing but I'm still +1 for no line as it is only meaningful if there is total order.

It's basically a bingo card - the more you fill out the higher chance for winning :)

[holly-cummins]

I grok why you feel something is missing but I'm still +1 for no line as it is only meaningful if there is total order.

It's basically a bingo card - the more you fill out the higher chance for winning :)

Well, only if bingo cards had some squares that actually had to be filled in in a certain order. "We've called 5, you can stamp that on your card, but folks, I'm afraid you can only stamp 5 if you've already stamped 62."

It's physically impossible to do a dev service without having done config support first. You can't have an advanced dev UI if you don't have basic dev UI. And it would be extremely hard to do most dev joy features without hooking your services up as CDI components. In deciding whether to get normal mode or dev mode or native mode working first, there's also a fairly strong natural order.

So it's a cross between a bingo card and something with progression. It would be great if we could find a way to indicate that, visually.

However, the dotted line may not be that way; George mentioned he was confused by it. So I'll go with majority vote and push the line-free graphic onto the branch.

[gastaldi]

Can we make this image a <map> and link to the sections below when someone clicks on a box?

[maxandersen]

So it's a cross between a bingo card and something with progression. It would be great if we could find a way to indicate that, visually.

The radar view shows the progress visually, the matrix card shows the details.

I think we are fine with we have and would rather have it go live ASAP and we can iterate from there :)

[maxandersen]

Can we make this image a <map> and link to the sections below when someone clicks on a box?

afaik asciidoc nor github markdown supports image map (or rather CSS in this day an age) to do that.

[quarkus-bot]

Status for workflow Quarkus Documentation CI

This is the status report for running Quarkus Documentation CI on commit 8180289.

✅ The latest workflow run for the pull request has completed successfully.

It should be safe to merge provided you have a look at the other checks in the summary.

[holly-cummins]

What's the next step on this PR, to get it merged? It sounds like there's general agreement that merging it would be a good idea, so I have optimistically squashed my commits.