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]

🎊 PR Preview 0c5417f has been successfully built and deployed to https://quarkus-pr-main-42446-preview.surge.sh/version/main/guides/

• Images of blog posts older than 3 months are not available.
• Newsletters older than 3 months are not available.

[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.

[holly-cummins]

I just read the preview (I had a 504, but a refresh fixed it).

I find surge previews 504 a lot. But the price is right. :)

I like this version a lot more! I think we need to add a bit more content in the text of each capabilities (it's a bit unbalanced right now), but that's a great first step.

🎉 I think I've managed to pad out the observability section so that the document is a bit less lopsided. We can also iterate once it's live, of course.

[maxandersen]

The new matrix is nice - but what does the dotted line supposed to mean/signal?

[holly-cummins]

The new matrix is nice - but what does the dotted line supposed to mean/signal?

It's intended to be the same line as in https://blog.container-solutions.com/hubfs/CS--LP__assets/CS--LP__images/mm_diagram.png, only I didn't change the colour either side of the line because it would be hard work, and I'm assuming we'll get James to draw something nicer.

So it's a progress mark, but with the distinction that we'd get blue areas to the right of the line, too. So I imagine it'd be a bit like this in a final render:

(I'm not sure we'd bother with the goal line, either, so maybe ignore that part of what I pasted.)

[maxandersen]

The new matrix is nice - but what does the dotted line supposed to mean/signal?

It's intended to be the same line as in https://blog.container-solutions.com/hubfs/CS--LP__assets/CS--LP__images/mm_diagram.png, only I didn't change the colour either side of the line because it would be hard work, and I'm assuming we'll get James to draw something nicer.

So it's a progress mark, but with the distinction that we'd get blue areas to the right of the line, too. So I imagine it'd be a bit like this in a final render:

(I'm not sure we'd bother with the goal line, either, so maybe ignore that part of what I pasted.)

gotcha - I like the one in the render as it does not have a strict order and if we actually remove the dotted line the progress is visible (all the blue vs green) and we can make a matrix that stays stable for any extension this way (if we wanted to) - just different levels of blue vs pink.

[holly-cummins]

My assumption is 100% that the text would stay stable for different extensions, just the areas that are coloured might be different.

Are we good to invoke @insectengine for graphic work, to produce something with the visual feel of , and the colours and words in my PR, or do we need to discuss more?

[maxandersen]

if its a matrix without a top level order as shown in the render then i think we are all good to get james to make it pretty.

the various areas/content we can iterate on and expand independent of the matrix.

[insectengine]

[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.

[quarkus-bot]

Status for workflow Quarkus Documentation CI

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

✅ 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.

[gastaldi]

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