diff --git a/README.md b/README.md
index 5ef4cbc..1acaa81 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,61 @@
-# The openSUSE Tumbleweed BCI OpenJDK 17 runtime container image
+# OpenJDK 17 runtime container image
+
 ![Redistributable](https://img.shields.io/badge/Redistributable-Yes-green)
 
-OpenJDK 17 runtime container based on the openSUSE Tumbleweed Base Container Image.
+## Description
+
+[OpenJDK](https://openjdk.org/) (Open Java Development Kit) is a free and open source implementation of the Java Platform, Standard Edition (Java SE). OpenJDK is the official reference implementation of Java SE since version 7.
+
+The OpenJDK runtime image is intended to be used as a runtime environment. For development, use the OpenJDK development image.
+
+## Usage
+
+To run a jar or war application inside a container instance, use the following command:
+
+```ShellSession
+$ podman run --rm -v "$PWD":/app:Z -w /app registry.opensuse.org/opensuse/bci/openjdk:17 java -jar hello.jar
+```
+
+Or create a new contained based on OpenJDK 17 runtime image:
+
+```Dockerfile
+FROM registry.opensuse.org/opensuse/bci/openjdk:17
+
+WORKDIR /app
+
+COPY . ./
+
+CMD ["java", "-jar", "hello.jar"]
+```
+
+To compile and deploy an application, copy the sources and build the application:
+
+```Dockerfile
+# Build the application using the OpenJDK development image
+FROM registry.suse.com/bci/openjdk-devel:17  as build
+
+WORKDIR /app
+
+COPY . ./
+
+RUN javac Hello.java
+
+# Bundle the application into OpenJDK runtime image
+FROM registry.opensuse.org/opensuse/bci/openjdk:17
+
+WORKDIR /app
+
+COPY --from=build /app/Hello.class /app
+
+CMD ["java", "Hello"]
+```
+
+Build and run the container image:
+
+```ShellSession
+$ podman build -t my-java-app .
+$ podman run -it --rm my-java-app
+```
 
 ## Licensing
 
diff --git a/openjdk-17-image.changes b/openjdk-17-image.changes
index c5b055b..34992eb 100644
--- a/openjdk-17-image.changes
+++ b/openjdk-17-image.changes
@@ -1,3 +1,8 @@
+-------------------------------------------------------------------
+Thu Jul 11 08:17:40 UTC 2024 - Alexandre Vicenzi <alexandre.vicenzi@suse.com>
+
+- extend README.md
+
 -------------------------------------------------------------------
 Tue Jun 25 10:04:26 UTC 2024 - Dirk Mueller <dmueller@suse.com>