docs: less detail in Hello World (#12)

Co-authored-by: Enno Runne <[email protected]>

docs/README.md

@@ -18,7 +18,7 @@ make managed
 
 2. Create the full site
 ```bash
-make local
+make local open
 ```
 
 This command will execute a Docker-based build process that compiles the documentation. The generated documentation will be output to the `target/site` directory.

docs/src/modules/ROOT/pages/index.adoc

@@ -53,12 +53,15 @@ Akka's event-sourced model is fundamentally streaming-based, providing a robust
 == Getting Started with Akka
 There are multiple ways to get started with Akka.
 
-* *Deploy, scale, and replicate a service.* Take the 5 minute walk-through by creating a free account at https://console.akka.io/register[akka.io].
-* *Learn* the Akka xref:concepts:architecture-model.adoc[] for architects and developers.
-* *Learn* the Akka xref:concepts:deployment-model.adoc[] for operators.
-* *Learn* the Akka xref:concepts:development-process.adoc[]
-* *Start a local development environment* Getting started with Integrated Development Environment (IDE) integration, local debugging, and packing services into images.  xref:java:running-locally.adoc[]
-* *Learn how to implement a "Hello World" service.* xref:java:author-your-first-service.adoc[]
-* *Review a pre-built service implementation.* See some Akka components in the xref:java:shopping-cart-quickstart.adoc[]
+* Hands-on
+** *Deploy, scale, and replicate a pre-built service.* Take the 5 minute walk-through by creating a free account at https://console.akka.io/register[akka.io].
+** *Implement a "Hello World" service.* xref:java:author-your-first-service.adoc[].
+** *Review a pre-built service implementation.* See some Akka components in the xref:java:shopping-cart-quickstart.adoc[].
+
+* Understand
+** ... the Akka xref:concepts:architecture-model.adoc[] for architects and developers.
+** ... the Akka xref:concepts:deployment-model.adoc[] for operators.
+** ... the Akka xref:concepts:development-process.adoc[].
+* *Start a local development environment* Getting started with Integrated Development Environment (IDE) integration, local debugging, and packing services into images. See xref:java:running-locally.adoc[].
 * *Setup* CI/CD pipelines, external Docker repositories, external messaging brokers, or 3rd party observability.
 See xref:operations:index.adoc[Operating Services] for more information.

docs/src/modules/java/pages/author-your-first-service.adoc

@@ -16,7 +16,7 @@ NOTE: If you'd rather skip past this and want to review an already completed app
 
 == Prerequisites
 
-include::ROOT:partial$cloud-dev-prerequisites.adoc[]
+include::ROOT:partial$local-dev-prerequisites.adoc[]
 
 
 == Generate and build the skeleton project
@@ -152,27 +152,18 @@ curl localhost:9000/hello/hello/Bob/30
 
 === Request body ===
 
-To accept an HTTP JSON body, specify a parameter that is a class that https://github.com/FasterXML/jackson?tab=readme-ov-file#what-is-jackson[Jackson] can deserialize:
+To accept an HTTP JSON body, specify a parameter that is a Java record.
 
 [source,java]
 .HelloWorldEndpoint.java
 ----
 include::example$doc-snippets/src/main/java/com/example/api/ExampleEndpoint.java[tag=request-body]
 ----
-<1> A class that Jackson can serialize and deserialize to JSON
+<1> The record will serialized and deserialized as JSON
 <2> A parameter of the request body type
 <3> When combining request body with path variables
 <4> The body must come last in the parameter list
 
-Additionally, the request body parameter can be of the following types:
-
- * `String` for any request with a text content type, the body decoded into a string
- * `java.util.List<T>` where `T` is a type Jackson can deserialize, accepts a JSON array.
- * `akka.http.javadsl.model.HttpEntity.Strict` for the entire request body as bytes together with the content type for
-   arbitrary payload handling.
- * `akka.http.javadsl.model.HttpRequest` for a low level, streaming representation of the entire request
-    including headers. See xref:http-endpoints.adoc#_low_level_requests[] below for more details
-
 You can now call these commands as well
 [source, command line]
 ----
@@ -182,30 +173,19 @@ curl -i -XPOST -H "Content-Type: application/json" localhost:9000/hello/hello -d
 
 === Response body ===
 
-To return response with JSON, the return value can be a class that Jackson can serialize:
+To return response with JSON, the return value can be a record that gets serialized as JSON:
 
 [source,java]
 .HelloWorldEndpoint.java
 ----
 include::example$doc-snippets/src/main/java/com/example/api/ExampleEndpoint.java[tag=response-body]
 ----
-<1> Returning an object that Jackson can serialize into JSON
-
-In addition to an object that can be turned to JSON, a request handler can return the following:
-
- * `null` or `void` to return an empty body.
- * `String` to return a UTF-8 encoded `text/plain` HTTP response.
- * `CompletionStage<T>` to respond based on an asynchronous result.
-  ** When the completion stage is completed with a `T` it is
-   turned into a response.
-  ** If it is instead failed, the failure leads to an error response according to
-   the error handling explained in xref:http-endpoints.adoc#_error_responses[error responses].
- * `akka.http.javadsl.model.HttpResponse` for complete control over the response, see xref:http-endpoints.adoc#_low_level_responses[] below
+<1> Returning a record that gets serialized as JSON
 
 [source, command line]
 ----
 curl localhost:9000/hello/hello/Bob/30
 ----
 
 == Next steps
-Now that you have a basic service running, it's time to learn more about building real services in Akka. See the xref:java:shopping-cart-quickstart.adoc[] to build a more realistic application.
+Now that you have a basic service running, it's time to learn more about building real services in Akka. See the xref:java:shopping-cart-quickstart.adoc[] to build a more realistic application and learn how to deploy it to https://console.akka.io[akka.io].