Improvement to WildFly documentation website

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Improvement to WildFly documentation website

Jean-Frederic Mesnil
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 -- [hidden email]
To unsubscribe send an email to [hidden email]
%(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s
Reply | Threaded
Open this post in threaded view
|

Re: Improvement to WildFly documentation website

Martin Stefanko
+1. IMHO very good idea.


Martin


On 6/9/21 10:23 AM, Jean-Frederic Mesnil 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 -- [hidden email]
> To unsubscribe send an email to [hidden email]
> %(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s
_______________________________________________
wildfly-dev mailing list -- [hidden email]
To unsubscribe send an email to [hidden email]
%(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s
Reply | Threaded
Open this post in threaded view
|

Re: Improvement to WildFly documentation website

James Perkins
In reply to this post by Jean-Frederic Mesnil
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 https://github.com/wildfly/wildfly.github.io where the docs are hosted now, but it's a bit odd IMO. It's only really got one "source file" which is the 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 <[hidden email]> 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?

I think this makes sense. I'm a +1 for investigating it for sure.
 

Jeff




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


--
James R. Perkins
JBoss by Red Hat

_______________________________________________
wildfly-dev mailing list -- [hidden email]
To unsubscribe send an email to [hidden email]
%(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s
Reply | Threaded
Open this post in threaded view
|

Re: Improvement to WildFly documentation website

Brian Stansberry
In reply to this post by Jean-Frederic Mesnil
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 <[hidden email]> 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 -- [hidden email]
To unsubscribe send an email to [hidden email]
%(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s


--
Brian Stansberry
Principal Architect, Red Hat JBoss EAP
He/Him/His

_______________________________________________
wildfly-dev mailing list -- [hidden email]
To unsubscribe send an email to [hidden email]
%(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s
Reply | Threaded
Open this post in threaded view
|

Re: Improvement to WildFly documentation website

James Perkins


On Wed, Jun 9, 2021 at 9:08 AM Brian Stansberry <[hidden email]> wrote:
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

That's a good point on Wildscribe. That is currently generated via a maven plugin and copied into the generated site.
 

On Wed, Jun 9, 2021 at 3:24 AM Jean-Frederic Mesnil <[hidden email]> 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 -- [hidden email]
To unsubscribe send an email to [hidden email]
%(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s


--
Brian Stansberry
Principal Architect, Red Hat JBoss EAP
He/Him/His
_______________________________________________
wildfly-dev mailing list -- [hidden email]
To unsubscribe send an email to [hidden email]
%(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s


--
James R. Perkins
JBoss by Red Hat

_______________________________________________
wildfly-dev mailing list -- [hidden email]
To unsubscribe send an email to [hidden email]
%(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s