5:04 a.m.
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/3fb997df3cb9c8617c0a6083cc8563b...
There is nothing really new here (and we could have a template such as
https://github.com/jmesnil/wildfly/blob/3fb997df3cb9c8617c0a6083cc8563bd3...
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/63635ec1999cab416b933c062ab...
(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/