APP-3060 Documentation revamping, getting started

README.md

@@ -1,4 +1,4 @@
-# Symphony Java BDK 
+# Symphony BDK Java 
 [![CircleCI](https://circleci.com/gh/SymphonyPlatformSolutions/symphony-api-client-java.svg?style=shield)](https://circleci.com/gh/SymphonyPlatformSolutions/symphony-api-client-java)
 [![Known Vulnerabilities](https://snyk.io/test/github/SymphonyPlatformSolutions/symphony-api-client-java/badge.svg)](https://snyk.io/test/github/SymphonyPlatformSolutions/symphony-api-client-java)
 [![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.symphony.platformsolutions/symphony-api-client-java/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.symphony.platformsolutions/symphony-api-client-java)
@@ -9,33 +9,29 @@ The Symphony Java BDK helps you to create Bots and Applications on top of the [S
 
 Documentation about BDK features and usage is available under [docs](./docs/index.md) folder.
 
-## How to Build
+## Build from Source
+The Symphony BDK uses a Maven [build](https://maven.apache.org/) build. The instructions below use the [Maven Wrapper](https://github.com/takari/maven-wrapper)
+from the root of the source treen. The wrapper script serves as a cross-platform, self-contained bootstrap mechanism for
+the build system.
 
-As this project contains modules for the legacy SDK/BDK as well as for the 2.0 ones, some
-Maven are defined to make the build faster depending on which version you are working on.
-
-The BDK can be built and published to your local Maven cache using the [Maven Wrapper](https://github.com/takari/maven-wrapper). 
-
-**Build Legacy Modules**
-
-The `legacy` profile is activated by default so there is no specific argument to define to have
-it part of the build. However, it is also possible to skip legacy modules to be built using argument `-P -legacy`:
+### Before you start
+To build you will need [Git](https://docs.github.com/en/github/getting-started-with-github/set-up-git) and [JDK 8 or later](https://adoptopenjdk.net/).
+Be sure that your `JAVA_HOME` environment variable points to the `jdk1.8+` folder extracted from the JDK download.
 
+### Get the source
 ```shell script
-# build the legacy modules
-./mvnw clean install
-
-# skip building legacy modules
-./mvnw clean install -P -legacy
+git clone git@github.com:SymphonyPlatformSolutions/symphony-api-client-java.git
+cd symphony-api-client-java
 ```
-
-**Build BDK 2.0 Modules**
-
-Still in construction, the 2.0 modules are deactivated by default but can be activated through the Maven profile `2.0` : 
-
+### Build from the Command Line
+To compile, test and build all jars, use:
 ```shell script
-# build the 2.0 modules only, skip the legacy ones
-./mvnw clean install -P2.0,-legacy
+./mvnw clean package
+```
+### Install in local Maven repository
+To install all Symphony BDK jars in your local Maven repository, use:
+```shell script
+./mvnw clean install
 ```
 
 ## License

docs/activity.md → docs/activity-api.md

@@ -178,3 +178,6 @@ class HelloFormReplyActivity extends FormReplyActivity<FormReplyContext> {
 1. The `ActivityMatcher` ensures that activity logic is triggered only when the form with `id` "**hello-form**" has been 
 submitted from the action button "**submit**"
 2. The activity context allows to directly retrieve form values. Here the "**name**" `<text-field>` value
+
+----
+[Home :house:](./index.md)

docs/authentication.md

@@ -24,3 +24,6 @@ public class Example {
 }
 
 ```
+
+----
+[Home :house:](./index.md)

docs/configuration.md

@@ -130,3 +130,6 @@ The legacy configuration using by the Java SDK v1 is also supported in BDK Confi
 
 This legacy configuration can be also read from a file, an inputstream, a classpath and automatically
 translated to `BdkConfig` instance.
+
+----
+[Home :house:](./index.md)

docs/fluent.md → docs/fluent-api.md

@@ -49,3 +49,5 @@ that is available in BDK is:
 - Datafeed Service: `bdk.datafeed()`
 - Activities Registry: `bdk.activities()`
 
+----
+[Home :house:](./index.md)

docs/getting-started.md

@@ -0,0 +1,8 @@
+# Getting Started with Symphony BDK for Java
+
+This getting guide provides detailed information for beginners that want to bootstrap their first Symphony BDK project 
+in Java either from scratch or by using 
+
+----
+[Home :house:](./index.md)
+

docs/index.md

@@ -1 +1,19 @@
-# Symphony BDK Reference Documentation 
+# Symphony BDK Reference Documentation 
+
+This reference guide provides detailed information about the Symphony BDK. It provides comprehensive 
+documentation for all features and abstractions made on top of the [Symphony REST API](https://developers.symphony.com/restapi/reference).
+
+If you are just getting started with Symphony Bot developments, you may want to begin reading the 
+[Getting Started](./getting-started.md) guide. 
+
+The reference documentation consists of the following sections:
+
+| Section                                   | Description                                                           |
+|-------------------------------------------|:---------------------------------------------------------------------:|
+| [Getting Started](./getting-started.md)   | Introducing Symphony BDK for beginners                                |
+| [Configuration](./configuration.md)       | Configuration structure, formats, how to load from code               |
+| [Authentication](./authentication.md)     | RSA or certificate authentication, OBO, extension app authentication  |
+| [Fluent API](fluent-api.md)               | Java Fluent API usage                                                 |
+| [Message API](message.md)                 | Sending or searching messages, usage of templates                     |
+| [Activity API](activity-api.md)           | The Activity Registry, creating custom activities                     |
+

docs/message.md

@@ -65,3 +65,6 @@ The templates will be looked for in this order:
 * in the classpath
 * in the file system
 * lastly as a URL
+
+----
+[Home :house:](./index.md)