diff --git a/readme.md b/readme.md
index a50d3b99e65cac11ac32ca85cb294af39d6bcb8f..c88284fa3a80f48aa49fdaa94e61a4e17d42b027 100644
--- a/readme.md
+++ b/readme.md
@@ -14,35 +14,36 @@ The [spring-petclinic-angular project](https://github.com/spring-petclinic/sprin
 
 ![alt petclinic-ermodel](petclinic-ermodel.png)
 
-## Running petclinic locally
+## Running Petclinic locally
 
-### With maven command line
-```
+### With Maven command line
+```sh
 git clone https://github.com/spring-petclinic/spring-petclinic-rest.git
 cd spring-petclinic-rest
 ./mvnw spring-boot:run
 ```
 
 ### With Docker
-```
+```sh
 docker run -p 9966:9966 springcommunity/spring-petclinic-rest
 ```
 
 You can then access petclinic here: [http://localhost:9966/petclinic/](http://localhost:9966/petclinic/)
 
-There are actuator health check and info routes as well: 
+There is an actuator health check route as well:
 * [http://localhost:9966/petclinic/actuator/health](http://localhost:9966/petclinic/actuator/health)
-* [http://localhost:9966/petclinic/actuator/info](http://localhost:9966/petclinic/actuator/info)
 
-## OpenAPI REST API documentation presented here (after application start):
+## OpenAPI REST API documentation
 
-You can reach the swagger UI with this URL
+You can reach the Swagger UI with this URL (after application start):
 [http://localhost:9966/petclinic/](http://localhost:9966/petclinic/swagger-ui.html).
 
-You then can get the Open API description reaching this URL [localhost:9966/petclinic/v3/api-docs](localhost:9966/petclinic/v3/api-docs).
+You then can get the Open API description reaching this URL: [localhost:9966/petclinic/v3/api-docs](localhost:9966/petclinic/v3/api-docs).
 
 ## Screenshot of the Angular client
 
+See its repository here: https://github.com/spring-petclinic/spring-petclinic-angular
+
 <img width="1427" alt="spring-petclinic-angular2" src="https://cloud.githubusercontent.com/assets/838318/23263243/f4509c4a-f9dd-11e6-951b-69d0ef72d8bd.png">
 
 ## In case you find a bug/suggested improvement for Spring Petclinic
@@ -51,44 +52,40 @@ Our issue tracker is available here: https://github.com/spring-petclinic/spring-
 
 ## Database configuration
 
-In its default configuration, Petclinic uses an in-memory database (HSQLDB) which
-gets populated at startup with data.
-A similar setups is provided for MySql and PostgreSQL in case a persistent database configuration is needed.
-To run petclinic locally using persistent database, it is needed to change profile defined in application.properties file.
+In its default configuration, Petclinic uses an in-memory database (HSQLDB) which gets populated at startup with data.
+Similar setups are provided for MySql and PostgreSQL in case a persistent database configuration is needed. However, to populate them with sample data, you should follow additional instructions from either `src/main/resources/db/mysql/petclinic_db_setup_mysql.txt` (for MySQL) or `src/main/resources/db/postgresql/petclinic_db_setup_postgresql.txt` (for PostgreSQL) file.
 
-For MySQL database, it is needed to change param "hsqldb" to "mysql" in string
-```
+To run Petclinic locally using persistent database, it is also needed to change profile defined in `application.properties` file.
+
+For MySQL database, it is needed to change param `hsqldb` to `mysql` in the following line of `application.properies` file:
+```properties
 spring.profiles.active=hsqldb,spring-data-jpa
 ```
- defined in application.properties file.
+Before doing this, it would be good to check properties defined in `application-mysql.properties` file:
 
-Before do this, would be good to check properties defined in application-mysql.properties file.
-
-```
+```properties
 spring.datasource.url = jdbc:mysql://localhost:3306/petclinic?useUnicode=true
 spring.datasource.username=pc
-spring.datasource.password=petclinic 
-spring.datasource.driver-class-name=com.mysql.jdbc.Driver 
+spring.datasource.password=petclinic
+spring.datasource.driver-class-name=com.mysql.jdbc.Driver
 spring.jpa.database=MYSQL
 spring.jpa.database-platform=org.hibernate.dialect.MySQLDialect
 spring.jpa.hibernate.ddl-auto=none
-```      
+```
 
-You may also start a MySql database with docker:
+You may also start a MySql database with Docker:
 
-```
+```sh
 docker run --name mysql-petclinic -e MYSQL_ROOT_PASSWORD=petclinic -e MYSQL_DATABASE=petclinic -p 3306:3306 mysql:5.7.8
 ```
 
-For PostgeSQL database, it is needed to change param "hsqldb" to "postgresql" in string
-```
+For PostgeSQL database, it is needed to change param `hsqldb` to `postgresql` in the following line of `application.properties` file:
+```properties
 spring.profiles.active=hsqldb,spring-data-jpa
 ```
- defined in application.properties file.
-
-Before do this, would be good to check properties defined in application-postgresql.properties file.
+Before doing this, it would be good to check properties defined in `application-postgresql.properties` file:
 
-```
+```properties
 spring.datasource.url=jdbc:postgresql://localhost:5432/petclinic
 spring.datasource.username=postgres
 spring.datasource.password=petclinic
@@ -97,9 +94,9 @@ spring.jpa.database=POSTGRESQL
 spring.jpa.database-platform=org.hibernate.dialect.PostgreSQLDialect
 spring.jpa.hibernate.ddl-auto=none
 ```
-You may also start a Postgres database with docker:
+You may also start a Postgres database with Docker:
 
-```
+```sh
 docker run --name postgres-petclinic -e POSTGRES_PASSWORD=petclinic -e POSTGRES_DB=petclinic -p 5432:5432 -d postgres:9.6.0
 ```
 ## API First Approach
@@ -141,7 +138,7 @@ In its default configuration, Petclinic doesn't have authentication and authoriz
 
 ### Basic Authentication
 In order to use the basic authentication functionality, turn in on from the application.properties file
-```
+```properties
 petclinic.security.enable=true
 ```
 This will secure all APIs and in order to access them, basic authentication is required.
@@ -153,7 +150,7 @@ The existing roles are listed below with the corresponding permissions
 
 There is an existing user with the username `admin` and password `admin` that has access to all APIs.
  In order to add a new user, please use the following API:
-```
+```json
 POST /api/users
 {
     "username": "secondAdmin",
@@ -180,7 +177,7 @@ If m2e is not there, just follow the install process here: http://eclipse.org/m2
 ### Steps:
 
 1) In the command line
-```
+```sh
 git clone https://github.com/spring-petclinic/spring-petclinic-rest.git
 ```
 2) Inside Eclipse
@@ -203,13 +200,11 @@ File -> Import -> Maven -> Existing Maven project
 
 ## Publishing a Docker image
 
-This application uses [Google Jib]([https://github.com/GoogleContainerTools/jib) to build an optimized Docker image
-into the [Docker Hub](https://cloud.docker.com/u/springcommunity/repository/docker/springcommunity/spring-petclinic-rest/)
-repository.
+This application uses [Google Jib]([https://github.com/GoogleContainerTools/jib) to build an optimized Docker image into the [Docker Hub](https://cloud.docker.com/u/springcommunity/repository/docker/springcommunity/spring-petclinic-rest/) repository.
 The [pom.xml](pom.xml) has been configured to publish the image with a the `springcommunity/spring-petclinic-rest`image name.
 
 Command line to run:
-```
+```sh
 mvn compile jib:build -X -DjibSerialize=true -Djib.to.auth.username=xxx -Djib.to.auth.password=xxxxx
 ```
 
@@ -232,4 +227,3 @@ For pull requests, editor preferences are available in the [editor config](https
 
 
 
-