diff --git a/java/README-content.md b/java/README-content.md
index f0f2caeb2..285b5e78a 100644
--- a/java/README-content.md
+++ b/java/README-content.md
@@ -1 +1,32 @@
+Java is a concurrent, class-based, object-oriented language specifically designed to have as few implementation dependencies as possible. It is inteneded to allow application developers to "write once, run anywhere", meaning that code that runs on one platform does not need to be recompiled to run on another.
+
 Java is a registered trademark of Oracle and/or its affiliates.
+
+> [wikipedia.org/wiki/Java_(programming_language)](http://en.wikipedia.org/wiki/Java_(programming_language))
+
+# How to use this image
+
+## Start a java instance running your app
+
+For this image, the most straight-forward use is to use a java container as both the build environment as well as the runtime environment. In your Dockerfile, you can do something along the lines of the following will compile and run your project.
+
+    FROM java
+    ADD . /usr/src/myapp
+    WORKDIR /usr/src/myapp
+    RUN javac Main.java
+    CMD ["java Main"]
+
+Then run the commands to build and run the docker image.
+
+    docker build -t my-java-app .
+    docker run -it --rm --name my-running-app my-java-app
+
+## Compile your app inside the docker container.
+
+It is not always appropriate to run your app inside a container. In instances where you only want to compile inside the docker instance, you can do something along the lines of the following.
+
+    docker run --rm -v "$(pwd)":/usr/src/myapp -w /usr/src/myapp java javac Main.java
+
+This will add your current directory as a volume to the comtainer, set the working directory to the volume, and run the command `javac Main.java` which will tell java to compile the code in Main.java and output the java class file to Main.class. Alternatively, if you have a make file, you can instead run the make command inside your container.
+
+    docker run --rm -v "$(pwd)":/usr/src/myapp -w /usr/src/myapp java make
diff --git a/java/README.md b/java/README.md
index 7271e6e63..c0c9c875c 100644
--- a/java/README.md
+++ b/java/README.md
@@ -1,5 +1,36 @@
+Java is a concurrent, class-based, object-oriented language specifically designed to have as few implementation dependencies as possible. It is inteneded to allow application developers to "write once, run anywhere", meaning that code that runs on one platform does not need to be recompiled to run on another.
+
 Java is a registered trademark of Oracle and/or its affiliates.
 
+> [wikipedia.org/wiki/Java_(programming_language)](http://en.wikipedia.org/wiki/Java_(programming_language))
+
+# How to use this image
+
+## Start a java instance running your app
+
+For this image, the most straight-forward use is to use a java container as both the build environment as well as the runtime environment. In your Dockerfile, you can do something along the lines of the following will compile and run your project.
+
+    FROM java
+    ADD . /usr/src/myapp
+    WORKDIR /usr/src/myapp
+    RUN javac Main.java
+    CMD ["java Main"]
+
+Then run the commands to build and run the docker image.
+
+    docker build -t my-java-app .
+    docker run -it --rm --name my-running-app my-java-app
+
+## Compile your app inside the docker container.
+
+It is not always appropriate to run your app inside a container. In instances where you only want to compile inside the docker instance, you can do something along the lines of the following.
+
+    docker run --rm -v "$(pwd)":/usr/src/myapp -w /usr/src/myapp java javac Main.java
+
+This will add your current directory as a volume to the comtainer, set the working directory to the volume, and run the command `javac Main.java` which will tell java to compile the code in Main.java and output the java class file to Main.class. Alternatively, if you have a make file, you can instead run the make command inside your container.
+
+    docker run --rm -v "$(pwd)":/usr/src/myapp -w /usr/src/myapp java make
+
 # Issues and Contributing
 
 We are always thrilled to receive pull requests, and do our best to process them as fast as possible. Not sure if that typo is worth a pull request? Do it! We will appreciate it.