Hi, 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 that gap. 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 https://antora.org to manage our community documentation at https://docs.wildfly.org.

This documentation site generator is able to aggregate documentation across multiple repositories and provide versioned documentation. It is used by Smallrye for their docs: https://smallrye.io/docs/index/index/index.html 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: https://smallrye.io/docs/smallrye-metrics/3.0.0/index.html https://smallrye.io/docs/smallrye-metrics/2.4.0/index.html I’m envisioning to restructure our community documentation with something like: docs.wildfly.org (generated by Antora)> | +- WildFly (from https://github.com/wildfly/wildfly docs) | +- Galleon (from https://github.com/wildfly/galleon) | +- Bootable Jar (from https://github.com/wildfly-extras/wildfly-jar-maven-plugin) | +- 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 https://github.com/wildfly/wildfly-charts) | +- 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 WildFly releases. 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?

Jeff -- Jeff Mesnil Principal Software Engineer Red Hat http://jmesnil.net/ _______________________________________________ wildfly-dev mailing list -- wildfly-dev(a)lists.jboss.org To unsubscribe send an email to wildfly-dev-leave(a)lists.jboss.org %(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s

Basic concept sounds good to me. Can it handle a bunch of static (i.e. already generated) content? I'm thinking of 1) old stuff (i.e. if we don't want to break all the existing URLs). I guess it can regenerate from tags, but that misses some cases where we tweaked things after the tag. 2) wildscribe

On Wed, Jun 9, 2021 at 3:24 AM Jean-Frederic Mesnil <jmesnil(a)redhat.com&gt; wrote: > Hi, > > 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 > that gap. > > 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 > https://antora.org to manage our community documentation at > https://docs.wildfly.org. > > This documentation site generator is able to aggregate documentation > across multiple repositories and provide versioned documentation. > > It is used by Smallrye for their docs: > https://smallrye.io/docs/index/index/index.html > > 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: > > https://smallrye.io/docs/smallrye-metrics/3.0.0/index.html > https://smallrye.io/docs/smallrye-metrics/2.4.0/index.html > > I’m envisioning to restructure our community documentation with something > like: > > docs.wildfly.org (generated by Antora)> > | > +- WildFly (from https://github.com/wildfly/wildfly docs) > | > +- Galleon (from https://github.com/wildfly/galleon) > | > +- Bootable Jar (from > https://github.com/wildfly-extras/wildfly-jar-maven-plugin) > | > +- 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 > https://github.com/wildfly/wildfly-charts) > | > +- 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 > WildFly releases. > 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? > > Jeff > > > > > -- > Jeff Mesnil > Principal Software Engineer > Red Hat > http://jmesnil.net/ > _______________________________________________ > wildfly-dev mailing list -- wildfly-dev(a)lists.jboss.org > To unsubscribe send an email to wildfly-dev-leave(a)lists.jboss.org > %(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s -- Brian Stansberry Principal Architect, Red Hat JBoss EAP He/Him/His _______________________________________________ wildfly-dev mailing list -- wildfly-dev(a)lists.jboss.org To unsubscribe send an email to wildfly-dev-leave(a)lists.jboss.org %(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s