I played a bit more around this task and I have something that might be worth showcasing as it impacts a lot of objectives we set for WildFly.

This revolves around having task-oriented guides that lets the user know how they could achieve something for their applications.
For example, what does it take to use MicroProfile Config with WildFly? How can I automate WildFly installations with Ansible? How can I build a container image with my Jakarta EE application? How can I setup TLS on Kubernetes?

All these informations are available at different places (GitHub projects, blog posts on wildfly.org or other places, docs.wildfly.org) but it’s very difficult to find them, make them consistent, and navigate from one to another...

The idea would be to have a single location where uses could *start from* and then link to other places.

The first step is to let the users « get started » with WildFly. That was the start of this mail thread and I have a PoC for that at http://jmesnil.github.io/wildfly.org/

The « get started » page explains in 4 steps how to create, build and run a Jakarta EE application with WildFly in less than 10 minutes (it’s using a Maven archetype that has not been released yet).

Then what next for the user?
We could have a « guides" section in wildfly.org that gathers all these task-oriented guides and let the user find the one they need to achieve their goals.

My PoC is doing that at http://jmesnil.github.io/wildfly.org/guides/

I’ve added a few guides to fill the content, the most realistic being http://jmesnil.github.io/wildfly.org//guides/use-microprofile-config. After I read this, I have been able to use MicroProfile Config with my app and I have learnt where I can find next steps and addition information.

The source of these guides would be in https://github.com/wildfly/wildfly/tree/main/docs/src/main/asciidoc. Having the doc being closer to the source will incentivize developers to add and maintain them :)

When we release a version of WildFly, we take that content from the tag and copy it to the web site.
We need to add a bit of metadata to display the guides with the right categories.

As an example, we recently had an article that explains how to use WildFly with Ansible at https://www.wildfly.org/news/2023/01/10/ansible-wildfly/

We could use this content to create a task-oriented guide by adding a commit to WildFly:

https://github.com/wildfly/wildfly/commit/3fb997df3cb9c8617c0a6083cc8563bd3729af7b

There is nothing really new here (and we could have a template such as https://github.com/jmesnil/wildfly/blob/3fb997df3cb9c8617c0a6083cc8563bd3729af7b/docs/src/main/asciidoc/guides/template.adoc to make sure the structure is consistent)

Now, when we do a release of WildFly, we would take all this content and copy that to github.com/wildfly/wildfly.org.
We would also add a bit of metadata to categorise the new guides.
For this example, we would commit something like

https://github.com/wildfly/wildfly.org/commit/63635ec1999cab416b933c062abde9486998b3af

(Note that only the guide.yaml needs curating, all other content is copied verbatim from the wildly repo without any modification.)

The web site will be published, the guides will be properly rendered with wildfly.org look & feel and categorized: http://jmesnil.github.io/wildfly.org//guides/automate-with-ansible

I looked at how https://quarkus.io/guides/ achieve this. They provide versioned guides (although they are only providing specific Quarkus LTS version afaict) and we could do the same.
But I’m not sure this is the right thing to do for guides if we multiply them for every version without a good reason.
It needs more insight but we could keep all this content in doc.wildfly.org for every version and make sure that wildfly.org would only provide the latest.

Who would be interested to work on this and bootstrap the effort?

Best regards,
Jeff

—
Jeff Mesnil
Engineer @ Red Hat JBoss EAP
http://jmesnil.net/
_______________________________________________
wildfly-dev mailing list -- wildfly-dev@lists.jboss.org
To unsubscribe send an email to wildfly-dev-leave@lists.jboss.org
Privacy Statement: https://www.redhat.com/en/about/privacy-policy
List Archives: https://lists.jboss.org/archives/list/wildfly-dev@lists.jboss.org/message/UE3ER5FEGH7VLZ64BIC75G2QMVA3SXUO/