doc: introduce architecture documentation (#160)

README.adoc

@@ -14,6 +14,8 @@ endif::[]
 :url-nvm: https://github.com/creationix/nvm
 :url-nvm-install: {url-nvm}#installation
 
+image::https://api.netlify.com/api/v1/badges/df65c069-bb52-46d2-8bf0-8e16b6b21482/deploy-status[alt=Netlify Status,link=https://app.netlify.com/sites/documentation-bonita/deploys]
+
 
 *_DISCLAIMER: this is a work in progress._*
 
@@ -22,6 +24,8 @@ endif::[]
 
 Static site generation based on {url-antora}[Antora] using {url-asciidoctor}:[Asciidoctor] documentation content stored in various Git repositories.
 
+More details are available in the xref:docs/architecture.adoc[Architecture Documentation].
+
 
 == Build
 

docs/README.adoc

 = Developers documentation
 
-* migration from the old documentation site
+* xref:configure-netlify-redirects.adoc[Configure netlify redirects]
+* xref:architecture.adoc[Architecture Overview]
+* Tips for Documentation Content Writers
+** xref:documentation-versions.adoc[Documentation Content Versions]
+* migration from the old documentation site (archives)
 ** xref:./migrate-from-old-documentation-site/doc-content-conversion-from-md-to-adoc.adoc[Convert markdown content to asciidoctor]
 ** xref:./migrate-from-old-documentation-site/migration-steps-put-the-site-live.adoc[Migration to put the site live]
-* xref:configure-netlify-redirects.adoc[Configure netlify redirects]

docs/architecture.adoc

+= Documentation Site architecture
+
+This document provides details on the architecture of the documentation site, in order to ease future developments.
+
+== Chore solution: https://antora.org/[Antora]
+
+Antora is a multi-repository documentation site generator.
+
+The Antora playbook is configured by the file _antora-playbook.yml_. +
+This configuration file lists all the components, and the branches to build. It also references the UI bundle and some additional Asciidoctor extensions, both used to generate the HTML.
+
+The Antora generator retrieves Asciidoctor sources from our documentation content repositories, and then generate a static HTML website from those sources.
+
+[NOTE]
+====
+A GitHub workflow is available to generate this static documentation (useful for oldest version not host on this documentation site).
+====
+
+== UI Bundle
+
+The UI bundle source repository can be found here: https://github.com/bonitasoft/bonita-documentation-theme[bonita-documentation-theme].
+
+The UI Bundle architecture is detailed on the UI bundle Readme.
+
+== Search solution: Algolia
+
+Because of our open source status, https://docsearch.algolia.com/[DocSearch by Algolia] offers us freely a search solution (Thanks a lot to them! ❤️). +
+The configuration file can be found https://github.com/algolia/docsearch-configs/blob/master/configs/bonitasoft.json[here].
+This file indicates to the DocSearch crawler the pages to crawl, and the elements to index.
+
+
+== Host solution: Netlify
+
+The documentation is hosted on https://app.netlify.com/sites/documentation-bonita[Netlify].
+
+Netlify allow us to manage redirection with the `netlify.toml` file at root of this repository.
+
+== Preview with Surge
+
+https://surge.sh/[Surge] let us deploy previews for the
+
+* theme development
+* site development
+* documentation preview when updating the content with Pull Requests
+
+

docs/documentation-versions.adoc

+= Documentation Versions
+:icons: font
+ifdef::env-github[]
+:note-caption: :information_source:
+:tip-caption: :bulb:
+:important-caption: :heavy_exclamation_mark:
+:caution-caption: :fire:
+:warning-caption: :warning:
+endif::[]
+
+CAUTION: this is a work in progress
+
+NOTE: the following mainly applies to the Bonita Platform documentation part
+
+image::images/DocToCloud-Architecture-BigPicture.png[]
+
+== Bonita versions that are documented
+
+For Bonita, the rule is the following one: +
+We document the 4 currently supported Bonita versions, and **the 4 versions before**. +
+
+== Impact on Algolia DocSearch
+
+Each time a new version of a documented Bonitasoft project is released, this DocSearch configuration file has to be updated:
+
+- The latest version has to be added to the projects to index
+- The oldest version should be removed from the projects to index
+
+-> It means that the DocSearch conf file should reflect this behavior.