[wildfly-dev] Re: WildFly documentation and UX for galleon packs and layers

TL:DR; WildFly documentation has not kept pace with the flexibility we added with Galleon feature packs and Glow. How can we improve it? I have been using several WildFly feature packs the last few weeks in which I've not been involved in and I noticed a few improvements we could make to our documentation that would greatly reduce the friction and make for a better developer experience. For a traditional way to use WildFly (donwload the server zip, build your deployments and deploy it), the documentation experience mostly comes from 2 places: * the WildFly model reference[1] that describes what WildFly is providing * the Jakarta EE[2] & MicroProfile[3] APIs that we are using to write the applications However, with the use of Galleon feature packs, the documentation and model reference are no longer captured and deliver to the developers. If I want to use the API X in my applications, what are the feature packs & layers that I need to provision for WildFly? WildFly Glow has introduced a set of rules that binds layers to these APIs. So for example if I'm using the MicroProfile Health API[4], this API is enabled by the "microprofile-config" layer. These rules are only used within WildFly Glow but I think there is values in exposing them to developers. Ideally, when I want to try a new API, I would have liked to answers questions like: * Which layer do I need to provision when I'm using the Langchain4J API? * Which feature pack is providing that layer? * What are the resources contributed by this layer? * What are the layers that provides LLM integrations? * For the ollama layer that I want to use, how can I configure these resources? (I'm using the WildFly AI feature pack but this is just an example of the friction I've encountered) We have all the code in place to answer these questions but they are sprinkled in many Git repositories and you must know what you are looking for to get answers: * Which layer do I need to provision when I'm using the Langchain4J API? => the "ai" layer (as described in https://github.com/wildfly-extras/wildfly-ai-feature-pack/blob/main/ai-fe... ) * Which feature pack is providing that layer? => the "org.wildfly:wildfly-ai-galleon-pack" is providing this layer (as described at https://github.com/wildfly-extras/wildfly-ai-feature-pack/tree/main?tab=r... ) * What are the resources contributed by this layer? => the "ai" spec defines them at https://github.com/wildfly-extras/wildfly-ai-feature-pack/blob/main/ai-fe... but we don't have a generated model reference for them * What are the layers that provides LLM integrations? => they are listed at https://github.com/wildfly-extras/wildfly-ai-feature-pack/tree/main/ai-fe... * For the ollama layer that I want to use, how can I configure these resources? => the spec defines them at https://github.com/wildfly-extras/wildfly-ai-feature-pack/blob/main/ai-fe... but I don’t have their model reference => the default Ollama model is llama3.1:8b and can be configured with the expresion "org.wildfly.ai.ollama.chat.model.name" (using the ORG_WILDFLY_AI_OLLAMA_CHAT_MODEL_NAME env var) or with the OLLAMA_CHAT_MODEL_NAME env var (from https://github.com/wildfly-extras/wildfly-ai-feature-pack/blob/b0a59b9ba6... ) I don't have a strong opinion for where I want to go but looking at what we did with WildFly Glow, we have a strong foundation to capture all these data. The https://github.com/wildfly/wildfly-galleon-feature-packs is a "magical" Git repository that lists for every version of WildFly the feature packs that we provide. From there, we should be able to find the layers that are contributed by these feature packs, the API that they provide and the resources they install. From these resources, we should be able to end up with something very similar to the model reference with the description of the resources, their default values, units, the expressions that can be used to customize them, etc. Ideally, I would like to end with a web site that tells me: * WildFly 35.0.1.Final is supporting LangChain4j with its "org.wildfly:wildfly-ai-galleon-pack" feature pack and its "ai" layer. * This galleon pack is incubating and is subject to changes. * If you want to use Ollama, this galleon pack also provides the ollama-chat-model, ollama-embedding-model, and ollama-streaming-chat-model * The ollama-chat-model has a default temperature of 0.9 that can be customized with the env var ORG_WILDFLY_AI_OLLAMA_CHAT_TEMPERATURE I'm thinking about creating a WildFly proposal to capture these doc/UX improvements as they will be relevant to all the feature packs we are delivering (including WildFly itself) as well as having the tools for user feature packs that are not curated by WildFly Glow. Traditionally we have used WildScribe to generate the Model reference that we publish in our docs but I’m not sure how much can be reused from this top down approach where I want to know which resources are contributed by which layer & galleon pack. What do you think? [1] https://docs.wildfly.org/35/wildscribe/ [2] https://jakarta.ee/specifications/platform/10/apidocs/ [3] https://javadoc.io/doc/org.eclipse.microprofile/microprofile/latest/ [4] https://github.com/wildfly/wildfly/blob/8302c565354934b3a20f3c06abc4759a5... -- Jeff Mesnil Engineer @ Red Hat http://jmesnil.net/