Hi Jeff et al,
First I would like to say I really think we need to add some love to our
docs in general. I know for sure we've got some broken links and stuff like
outdated information. It would be great if anyone/everyone could help
update the various things they may find. I've got a list of broken links
I've not been able to investigate, but would be happy to share or I'll get
to it hopefully sooner rather than later.
That said I feel the docs for at least WildFly itself should be a separate
project and not in WildFly itself. We've got
where the docs are hosted now,
but it's a bit odd IMO. It's only really got one "source file" which is
index and everything else is copied over from wildfly/docs after it's built.
It would be wonderful to restructure it so we could share pages as well.
On Wed, Jun 9, 2021 at 1:24 AM Jean-Frederic Mesnil <jmesnil(a)redhat.com>
With WildFly 24 almost out, now might be a good time to revisit our
community documentation at https://docs.wildfly.org
We are lacking a Cloud-oriented guide that describes how to build and
deploy WildFly applications on Kubernetes. We have a whole ecosystem around
this (operator, helm charts, S2I images, Bootable Jar + JKube) but the
documentation is spread around all these smaller projects and we don’t have
something that gives the high-level picture.
I would like to provide a “Getting Started on the Cloud” guide to fill
However I’m not sure where we could write this guide. I don’t think it
belongs to https://github.com/wildfly/wildfly/tree/master/docs
So another related thing I would like is to evaluate using
to manage our community documentation at
This documentation site generator is able to aggregate documentation
across multiple repositories and provide versioned documentation.
It is used by Smallrye for their docs:
As you can see each individual projects maintains its documentation but
they are all aggregated in a single place.
There is also the ability to access different version of the documentation:
I’m envisioning to restructure our community documentation with something
(generated by Antora)>
+- WildFly (from https://github.com/wildfly/wildfly
+- Galleon (from https://github.com/wildfly/galleon
+- Bootable Jar (from
+- WildFly on the Cloud
| +- Getting started Guide (from I don’t know where)
| +- WildFly S2I (from https://github.com/wildfly/wildfly-s2i
| +- WildFly Operator (from https://github.com/wildfly/wildfly-operator
| +- Helm Chart for WildFly (from
+- Other WildFly-related documentation/guide (e.g Elytron, Clustering)
The advantage of that approach is that each project manages its doc
individually and do not have to a kind of Big Bang release when we deliver
We still have to provide some consistency though.
We could also have a dedicated section for task-oriented guides:
* Connect to Keycloak on Kubernetes
* Clustering Guide for the Cloud
* Integrated with Apache Kafka
It’s not clear to me how these guides relates to our quickstarts though…
What do you think? Is this something worth investigating?
I think this makes sense. I'm a +1 for investigating it for sure.
Principal Software Engineer
wildfly-dev mailing list -- wildfly-dev(a)lists.jboss.org
To unsubscribe send an email to wildfly-dev-leave(a)lists.jboss.org
James R. Perkins
JBoss by Red Hat