[README.md] Refactoring of the README file (openhab#722)

* First deletions and adaptions of README.md. Signed-off-by: Jerome Luckenbach <[email protected]> * Started new introduction. Signed-off-by: Jerome Luckenbach <[email protected]> * Reworked external content area and versioning area. Signed-off-by: Jerome Luckenbach <[email protected]> * Improve README.md further Signed-off-by: Yannick Schaus <[email protected]> * One sentence per line. Signed-off-by: Jerome Luckenbach <[email protected]>
Redsandro · Jul 8, 2018 · d0f92a2 · d0f92a2
1 parent 0b51686
commit d0f92a2
Show file tree

Hide file tree

Showing 2 changed files with 48 additions and 57 deletions.
diff --git a/README.md b/README.md
@@ -8,89 +8,80 @@
 
 This repository contains the documentation for openHAB.
 
-The result is available at [http://docs.openhab.org/](http://docs.openhab.org/)
+The result is available at [https://www.openhab.org/docs/](https://www.openhab.org/docs/), [https://www.openhab.org/addons/](https://www.openhab.org/addons/) and [http://docs.openhab.org/](http://docs.openhab.org/) [Deprecated]
 
-## Contributing to the Documentation
-
-The documentation is a community effort, so everyone is welcome to suggest changes, add new sections and fix bugs.
-This is done exactly the same way as for the code repositories, simply through pull requests against this repo.
-Please read the [contribution guidelines](CONTRIBUTING.md) for details.
+## How it works
 
-### Prerequisites
+In this repo you can find and improve all *general* documentation contents.
+In fact that is all you can see in the `master` branch.
+There are also other *read-only* branches, which hold external content like the *add-ons* and *concepts* documentation.
+We will read about them later.
 
-Our documentation is built with Jekyll and served through Github Pages.
+### So I can't improve an add-on article here?
 
-In order to run Jekyll locally, you also need Ruby being installed.
-Please see the [Jekyll installation instructions](https://jekyllrb.com/docs/installation/) for details.
+Correct, this is done in the original repository of the add-on.
+You may want to know how to find the right file in all of those repos?
+This is fairly easy: 
+on most of the documentation pages on https://www.openhab.org/, 
+you will find the following link at the bottom, which will point you directly to the file you want to improve.
 
-An alternative for a local setup is a virtual machine provided by Vagrant.
+![Contribution link to a specific page](./images/contribution_link.png)
 
-### Serving locally
+When your improvement has been made and merged, we will get the updated article automatically through our build mechanism.
+This happens mostly once a day. Afterwards your change is included in the next build of the openHAB website.
 
-Once you have Jekyll installed and the repository checked out, simply run
+## Contributing to the Documentation
 
-```shell
-jekyll serve
-```
+The documentation is a community effort, so everyone is welcome to suggest changes, add new sections and fix bugs.
+This is done exactly the same way as for the code repositories, simply through pull requests against this repo.
+When editing a page through the _"Edit this page on GitHub"_ link on the website, you will be given the opportunity to
+create a pull request directly from GitHub. 
+Please read our [contribution guidelines](CONTRIBUTING.md) and try to follow
+them as bext as you can before submitting a change for review - but don't worry if you don't understand all of them, we
+will help you to get it right.
 
-from within the repository root folder and point your browser to [`http://localhost:4000`](http://localhost:4000).
-This will give you a preview of the documentation in the same way as it will appear on docs.openhab.org once your PR is merged.
-Changes to the markdown files will automatically be taken into account as Jekyll re-generates the pages on the fly.
+## So what are the other branches for?
 
-### Serving via Vagrant VM
+We use them to bring together all relevant articles or to archive versioned content.
+Mostly those branches will get updated automatically through our continuous integration builds.
+You can read a bit more below about our external ressources and how we get them.
 
-You can also have a virtual machine serving a Jekyll and webserver instance for you, without changing your base system or being limited by it.
-The virtual machine will run in the background, process your changes to the source and presenting the results on your hosts [`http://localhost:4000`](http://localhost:4000).
-A [Vagrant](https://www.vagrantup.com) machine configured by a [`Vagrantfile`](Vagrantfile) file is provided for that purpose.
+### Automatically Generated Parts
 
-You need to have [VirtualBox](https://www.virtualbox.org) and [Vagrant](https://www.vagrantup.com/downloads.html) installed.
-After that, it's as easy as:
+Those parts include __all__ add-on documentation files, no matter if they are from the Eclipse SmartHome repo, the
+`openhab1-addons` repo, the `openhab2-addons` repo or any special binding repo like *habmin*, *zwave* or the *alexa skill*.
+The "Concepts" articles also come from Eclipse SmartHome and are maintained there.
 
-```shell
-/path-to/openhab-docs$ vagrant up
-```
+We are keeping all those files at their original location, because it simply doesn't make sense to keep them here.
+Imagine you want to do an improvement of the zwave binding and have to update the readme file in a completely different place.
+That's twice the effort and also we would have to coordinate two Pull Requests.
+So we are saving time for everyone by keeping those files at their original location along with the code.
 
-## Automatically Generated Parts
+### How the documentation build works
 
-Please note that a few parts of this repository MUST NOT BE MANUALLY EDITED!
-These are copied from the source code repositories and some files are generated from them. These files/folders are:
+We have set up our [build server](https://openhab.ci.cloudbees.com/view/Documentation/) to do the magic automatically.
+There are several triggers (mostly time based), which will then *gather the external contents* and move them to our *final* branch.
+You can find this migrated external content in the *final* branch under:
 
-- `addons_*`
+- `_addons_*`
 - `concepts`
 
-The generation/update of these files can be triggered through `bash update-external-resources.sh` in the repo root.
-The process will create a temporary folder `.external-resources`, which is only used by the update script and can be ignored.
-
-## About the `_addons_*` Folders
-
-See [Jekyll Collections](https://jekyllrb.com/docs/collections/) for general details.
-The folders represent collections of the different Addons types.
-
-If you are here to help improve one of the contained READMEs, read carefully.
-These files are mere copies of files in other repositories and will be overwritten on a regular basis.
-Please find the original repository and add your contribution there.
-
-At the time of this writing, the folders are automatically created and updated by the toolchain
+You can even have a look at how this works in detail.
+The external content is updated by the following toolchain:
 
 - `update-external-resources.sh` → `pom.xml` → `process_addons.groovy`
 
-Configuration of the collections happens through `_config.yml`.
-The most important setting you need to be aware of, is, that all files in collections are mapped to certain paths:
-
-- e.g. `_addons_bindings\astro\readme.md` → [docs.openhab.org/addons/bindings/astro/readme.html](http://docs.openhab.org/addons/bindings/astro/readme.html)
-
-Check the mentioned files for more details.
+Everything that gets updated in the *master* branch will be also merged over to the *final* branch automatically.
+Afterwards we will redeploy the website with the latest content from the *final* branch at regular intervals.
 
 ## Documentation Versioning
 
-Just as openHAB is released in versions, the documentation website provides fixed versions of the documentation articles, e.g., [docs.openhab.org/v2.1/installation/linux.html](http://docs.openhab.org/v2.1/installation/linux.html)
+Just as openHAB is released in versions, the documentation website provides fixed versions of the documentation articles, e.g., [https://www.openhab.org/v2.2/installation/linux.html](https://www.openhab.org/v2.2/installation/linux.html)
 
-Please see [this issue](https://github.com/openhab/openhab-docs/issues/520#issuecomment-339741820) for all details regarding the current implementation.
+Please see [this issue](https://github.com/openhab/openhab-docs/issues/520#issuecomment-339741820) for all details regarding the tagging and branching approach.
 In short, the following has to be considered:
 
 - Versions like "2.1.0" are marked by git tags.
 - Based on tags branches like "2.1-patch" are created, to include later discovered changes (like fixed links).
-- The intended base folder for the version needs to be set in `_config.yml`, e.g. `baseurl: "/v2.1"`.
-- New versions have to be added to the dropdown menu shown on the resulting website, configured in `_includes/versioning.html`.
-- The version branch has to be generated with jekyll, the resulting content goes into the version folder identical to the above set baseurl. Execute e.g. `jekyll build -d path/to/checked-out/gh-pages-branch/v2.1/`
-- The generated static page files under, e.g., `v2.1/` need to be committed to `gh-pages` for GitHub Pages to pick them up and include in the generated page.
+
+When a version is tagged (or updated), a static version of the website has to be generated and copied into the correct sub-folder, this is currently a manual operation described succinctly here: https://github.com/openhab/website/issues/72
diff --git a/images/contribution_link.png b/images/contribution_link.png