Introduction fixes

docs/about/introduction.adoc

@@ -16,102 +16,118 @@
 
 ///////////////////////////////////////////////////////////////////////////////
 
-= About Helidon
-:description: about Helidon
+= Introduction
+:description: Helidon
 :keywords: helidon, java, microservices, microprofile
 :rootdir: {docdir}/..
 
 include::{rootdir}/includes/attributes.adoc[]
 
-Helidon is a collection of Java libraries for writing microservices that run on a fast web core powered by Netty. Its available in two frameworks: Helidon SE and Helidon MP.
+== Contents
 
-== A Collection of Java Libraries
+* <<What is Helidon?, What is Helidon?>>
+* <<Helidon Flavors, Helidon Flavors>>
+** <<What flavor shall I use?, What flavor shall I use?>>
+* <<Prerequisites, Prerequisites>>
+* <<Next Steps, Next Steps>>
 
-Helidon provides an open source, lightweight, fast, reactive, cloud native framework for developing Java microservices. Helidon implements and supports MicroProfile, a baseline platform definition that leverages Java EE and Jakarta EE technologies for microservices and delivers application portability across multiple runtimes.
+== What is Helidon?
 
+link:https://helidon.io[Helidon] is a collection of Java libraries for writing microservices that run on a fast web core powered by link:https://netty.io[Netty]. It's small, fast and fun to use. 
 
-== Using Cloud-native Tools with Helidon
+Helidon is open source under Alache 2.0 license. Sources are available on link:{helidon-github-tree-url}[GitHub].
 
-Helidon libraries interoperate with popular tools from the cloud-native space, so there's no need for any specific tooling or deployment model. Helidon can be used with:
+Helidon is cloud-native ready. It provides fast start-up time, has low memory consumption and small disk footprint. It also comes with full observability stack out of the box including Health Checks, Metrics, Tracing and Logging.
 
-* https://www.docker.com/[Docker]
-* https://kubernetes.io/[Kubernetes]
-* https://prometheus.io/[Prometheus]
-* https://opentracing.io/[OpenTracing]
-* https://coreos.com/etcd/[Etcd]
+Helidon fully supports GraalVM native-image allowing you to build native executable out of your Java application.
 
-TIP: The xref:prerequisites.adoc[Helidon Quickstart Examples]
- contain support for Docker and Kubernetes.
+== Helidon Flavors
 
-
-== Understanding the Helidon Frameworks
-Helidon supports two programming models for writing microservices: *Helidon SE* and *Helidon MP*.
-
-SE is designed to be a microframework that supports the reactive programming model, while Helidon MP is an Eclipse MicroProfile runtime that allows the Jakarta EE community to run microservices in a portable way.
-
-The table below shows to primary differences between Helidon SE and Helidon MP.
+Helidon comes in two flavors: *Helidon SE* and *Helidon MP*. Think about flavors as frameworks providing similar functionality using differet development experience.
 
 [cols="3,3"]
 |====================
 | *Helidon SE* |  *Helidon MP*
 
-|Helidon SE gives you full transparency and puts you in control.|Helidon MP is built on top of the Helidon libraries and provides platform definition that is familiar to enterprise Java developers.
-|Microframework model with a very small footprint and limited functionality (~7 MB) | https://projects.eclipse.org/proposals/eclipse-microprofile[Eclipse MicroProfile] implementation; slightly larger footprint than SE (~13 MB)
-|Functional style is reactive non-blocking   |Declarative style with dependency injection
-|Transparent "no magic" development experience; pure java application development with no annotations and no dependency injections  |Jakarta EE microprofile development experience; all Jakarta components (CDI, JAX-RS, JSON-P/B)
-|Learn more about xref:../se/introduction.adoc[Helidon SE]. | Learn more about xref:../mp/introduction/introduction.adoc[Helidon MP].
+|Helidon SE gives you full transparency and puts you in control.
+|Helidon MP is built on top of the Helidon SE libraries and provides platform definition that is familiar to enterprise Java developers.
+
+|Microframework model with a very small footprint and limited functionality (~7 MB) 
+| https://projects.eclipse.org/proposals/eclipse-microprofile[MicroProfile] implementation; slightly larger footprint than SE (~13 MB)
+
+|Functional style, reactive, non-blocking   
+|Declarative style with dependency injection
+
+|Transparent "no magic" development experience; pure java application development with no annotations and no dependency injections  
+|Spring Boot, Jakarta EE and MicroProfile development experience; Jakarta EE components (CDI, JAX-RS, JSON-P/B)
+
+|Learn more about xref:{rootdir}/se/introduction.adoc[Helidon SE]. | Learn more about xref:{rootdir}/mp/introduction.adoc[Helidon MP].
 |====================
 
-== What's New in Helidon 2.0
-The Helidon 2.0 release contains significant new features, enhancements and fixes.
+To better understand differences below are two samples implementing a simple RESTful service. One is using Helidon SE, another Helidon MP.
+
+.Helidon SE sample
+[source,java]
+----
+Routing routing = Routing.builder()
+    .get("/hello", 
+        (req, res) -> res.send("Hello World"))
+    .build();
+
+WebServer.create(routing)
+    .start();
+----
 
-TIP: For a complete list of fixes and enhancements, see the Helidon 2.0
- https://github.com/oracle/helidon/blob/2.0.0/CHANGELOG.md[changelog].
+.Helidon MP sample
+[source,java]
+----
+@Path("hello")
+public class HelloWorld {
+    @GET
+    public String hello() {
+        return "Hello World";
+    }
+}
+----
 
-* *GraalVM Native-image Support in Helidon MP* +
-Helidon SE already supports GraalVM, but in 2.0 GraalVM native image support will also be available in Helidon MP.
- xref:../mp/guides/graalnative.adoc[GraalVM Native Images Guide] +
+=== What flavor shall I use?
 
-* *Helidon Command Line Tool* +
-One of the new features in Helidon 2.0 is the addition of a command line interface. The Helidon CLI enables developers
- to get started with Helidon with minimal effort: you can create a new application, build it, run it, and more, by
- writing some simple commands.
+Use Helidon SE if
 
-* *DB Client for Helidon SE* +
-The new database client for Helidon SE will include support for the MongoDB reactive driver and brings Health Checks,
- Metrics, and Tracing support to every Helidon API. xref:../se/dbclient.adoc[Learn more about the DB Client].
+- Performance is your main goal
+- You are familiar with Reactive Programming
+- Your application is heavily using concurrency
+- You are not planning to use any CDI based components
+- You want to use minimum number of third-party dependencies
 
-* *Extending MicroProfile Reactive Messaging and Reactive Operators Support* +
-MP Reactive Operators will be included in both frameworks, while MP Reactive Messaging will only be included in
- Helidon MP. xref:../mp/reactivemessaging/introduction.adoc[Learn more about Reactive Messaging] and
- xref:../mp/reactivestreams/rsoperators.adoc[Reactive Streams].
+Use Helidon MP if
 
-* *Helidon Web Client* +
-The new reactive web client can integrate with other Helidon SE APIs.
-xref:../se/webclient.adoc[Learn more about the Helidon Web Client].
+- You want to base your application on modern enterprise Java standards such as Jakarta EE and MicroProfile
+- You are familiar with Java EE, Jakarta EE or Spring Boot and would like to use similar development experience
+- You are migrating existing Java EE/Jakarta EE application to microservices
+- You are planning to use CDI components or extensions
+- You are planning to use JPA for data access and Jersey (JAX-RS) for RESTful services
 
-* *Additional Websocket Support* +
-Based upon the Tyrus implementation, Helidon receives WebSocket API support.
-xref:../se/websocket.adoc[Learn more about Websocket Support].
 
-* *Support for Java 17 APIs* +
-Helidon will require Java 17 or newer.
-xref:prerequisites.adoc[Learn more about the prerequisites for Helidon 2.0].
+[NOTE]
+====
+If you don't know which Helidon flavor to use – use *Helidon MP*
+====
 
-* *CORS support for MP and SE* +
-Although it is possible for any Helidon application to implement its own support for CORS, there are common tasks
- (such as processing preflight requests) that can be provided in a Helidon module.
- xref:../se/cors.adoc[Learn more about CORS support].
+== Prerequisites
 
-* *Backward Incompatible Changes* +
-View the following links for information about potential breaking changes, including package name changes:
+Helidon 3 requires Java 17 (or newer) and Maven. You need Docker if you want to build and deploy Docker containers. If you want to deploy to Kubernetes, you need `kubectl` and a Kubernetes cluster (you can xref:kubernetes.adoc[install one on your desktop]).
 
-** https://github.com/oracle/helidon/blob/2.0.0/CHANGELOG.md#backward-incompatible-changes-1[Backward incompatible changes in 2.0.0-RC2]
-** https://github.com/oracle/helidon/blob/2.0.0/CHANGELOG.md#backward-incompatible-changes-2[Backward incompatible changes in 2.0.0-RC1]
-** https://github.com/oracle/helidon/blob/2.0.0/CHANGELOG.md#backward-incompatible-changes-3[Backward incompatible changes in 2.0.0-M3]
-** https://github.com/oracle/helidon/blob/2.0.0/CHANGELOG.md#backward-incompatible-changes-4[Backward incompatible changes in 2.0.0-M2]
-** https://github.com/oracle/helidon/blob/2.0.0/CHANGELOG.md#backward-incompatible-changes-5[Backward incompatible changes in 2.0.0-M1]
+- https://www.oracle.com/technetwork/java/javase/downloads[Java{nbsp}SE{nbsp}17] (http://jdk.java.net[Open{nbsp}JDK{nbsp}17]) or newer
+- https://maven.apache.org/download.cgi[Maven 3.8.6+]
+- https://docs.docker.com/install/[Docker 18.09+]
+- https://kubernetes.io/docs/tasks/tools/install-kubectl/[Kubectl 1.16.5+]
+
+We are also strongly suggesting installing xref:cli.adoc[Helidon CLI] (Command Line Interface) which helps generating and building Helidon projects.
 
 == Next Steps
 
-Try the xref:prerequisites.adoc[Helidon Quickstart Examples].
+Next would be to choose a Helidon flavor and start using it. Check the following 
+
+- xref:{rootdir}/se/introduction.adoc[Helidon SE Documentation]
+- xref:{rootdir}/mp/introduction.adoc[Helidon MP Documentation]

docs/includes/attributes.adoc

@@ -37,7 +37,7 @@ endif::[]
 // versions
 :version-plugin-helidon: 3.0.0-M3
 
-:version-lib-microprofile-api: 3.3
+:version-lib-microprofile-api: 5.0
 
 // microprofile specifications
 :version-lib-microprofile-lra-api: 2.0-RC1
@@ -57,6 +57,7 @@ endif::[]
 :version-lib-jakarta-cdi: 3.0
 :version-lib-jakarta-websockets-api: 2.0
 :version-lib-jakarta-bean-validation: 2.0
+:version-lib-jakarta-jsonp-api: 2.0
 :version-lib-jakarta-jsonb-api: 2.0
 :version-lib-jakarta-transaction-api: 2.0
 :version-lib-jakarta-persistence-api: 3.0
@@ -104,8 +105,8 @@ endif::[]
 :microprofile-metrics-javadoc-annotation-url: {microprofile-metrics-javadoc-url}/org/eclipse/microprofile/metrics/annotation
 :microprofile-metrics-javadoc-metric-url: {microprofile-metrics-javadoc-url}/org/eclipse/microprofile/metrics
 
-:microprofile-tracing-base-url: {microprofile-base-url}/microprofile-tracing-{version-lib-microprofile-tracing}
-:microprofile-tracing-spec-url: {microprofile-tracing-base-url}/microprofile-tracing-spec-{version-lib-microprofile-tracing}.html
+:microprofile-tracing-base-url: {microprofile-base-url}/microprofile-opentracing-{version-lib-microprofile-tracing}
+:microprofile-tracing-spec-url: {microprofile-tracing-base-url}/microprofile-opentracing-spec-{version-lib-microprofile-tracing}.html
 :microprofile-tracing-javadoc-url: {microprofile-tracing-base-url}/apidocs
 
 :microprofile-health-base-url: {microprofile-base-url}/microprofile-health-{version-lib-microprofile-health}
@@ -133,7 +134,7 @@ endif::[]
 :microprofile-rest-client-javadoc-url: {microprofile-rest-client-base-url}/apidocs
 
 :microprofile-graphql-base-url: {microprofile-base-url}/microprofile-graphql-{version-lib-microprofile-graphql}
-:microprofile-graphql-spec-url: {microprofile-rest-graphql-url}/microprofile-rest-client-spec-{version-lib-microprofile-graphql}.html
+:microprofile-graphql-spec-url: {microprofile-graphql-base-url}/microprofile-graphql-spec-{version-lib-microprofile-graphql}.html
 :microprofile-graphql-javadoc-url: {microprofile-rest-graphql-url}/apidocs
 
 // Jakarta versioned URLs
@@ -152,6 +153,9 @@ endif::[]
 :jakarta-bean-validation-spec-url: {jakarta-bean-validation-base-url}/bean-validation_{version-lib-jakarta-bean-validation}.html
 :jakarta-bean-validation-javadoc-url: {jakarta-bean-validation-base-url}/apidocs
 
+:jakarta-jsonp-base-url: {jakarta-base-url}/jsonp/{version-lib-jakarta-jsonp-api}
+:jakarta-jsonp-javadoc-url: {jakarta-jsonp-base-url}/apidocs
+
 :jakarta-jsonb-base-url: {jakarta-base-url}/jsonb/{version-lib-jakarta-jsonb-api}
 :jakarta-jsonb-spec-url: {jakarta-jsonb-base-url}/jakarta-jsonb-spec-{version-lib-jakarta-jsonb-api}.html
 :jakarta-jsonb-javadoc-url: {jakarta-jsonb-base-url}/apidocs

docs/mp/grpc/server-side-services.adoc

@@ -33,7 +33,7 @@ include::{rootdir}/includes/mp.adoc[]
 - <<Usage, Usage>>
 
 == Overview
-The gRPC Microprofile APIs are an extension to xref:../introduction/introduction.adoc[Helidon MP] to allow building
+The gRPC Microprofile APIs are an extension to xref:{rootdir}/mp/introduction.adoc[Helidon MP] to allow building
 of gRPC services and clients that integrate with the Microprofile APIs. Using Helidon gRPC MP makes building gRPC services
 and clients an easier process compared to the traditional approach using Protobuf files and code generation. Services can be built
 using POJOs that are then discovered and deployed at runtime in the same way the Helidon MP discovers and deploys web resources