Merge pull request #103 from Icinga/recommend-to-install-from-packages

Recommend to install from packages

README.md

@@ -6,7 +6,7 @@
 
 ![Icinga Logo](https://icinga.com/wp-content/uploads/2014/06/icinga_logo.png)
 
-Hassle-free deep integration with Atlassian Jira™. Depending on your needs, this
+Hassle-free deep integration with Atlassian Jira. Depending on your needs, this
 module is able to:
 
 * create **Jira Issues for Problems** detected by Icinga

doc/02-Installation.md

@@ -0,0 +1,20 @@
+<!-- {% if index %} -->
+# Installing Icinga Web Jira Integration
+
+The recommended way to install Icinga Web Jira Integration
+and its dependencies is to use prebuilt packages for
+all supported platforms from our official release repository.
+Please note that [Icinga Web](https://icinga.com/docs/icinga-web) is required
+and if it is not already set up, it is best to do this first.
+
+The following steps will guide you through installing and setting up Icinga Web Jira Integration.
+<!-- {% else %} -->
+<!-- {% if not icingaDocs %} -->
+
+## Installing the Package
+
+If the [repository](https://packages.icinga.com) is not configured yet, please add it first.
+Then use your distribution's package manager to install the `icinga-jira` package
+or install [from source](02-Installation.md.d/From-Source.md).
+<!-- {% endif %} -->
+<!-- {% endif %} --><!-- {# end else if index #} -->

doc/02-Installation.md.d/From-Source.md

@@ -0,0 +1,15 @@
+# Installing Icinga Web Jira Integration from Source
+
+Please see the Icinga Web documentation on
+[how to install modules](https://icinga.com/docs/icinga-web-2/latest/doc/08-Modules/#installation) from source.
+Make sure you use `jira` as the module name. The following requirements must also be met.
+
+## Requirements
+
+* PHP (≥7.2)
+* [Icinga Web](https://github.com/Icinga/icingaweb2) (≥2.9)
+* Icinga Web libraries:
+  * [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (≥0.11)
+* Icinga Web modules:
+  * [Icinga DB Web](https://github.com/Icinga/icingadb-web) (≥1.0) or the `monitoring` module
+<!-- {% include "02-Installation.md" %} -->

doc/03-Configuration.md

@@ -1,29 +1,13 @@
-# Installation and Configuration
+# Configuration
 
-## Requirements
-
-* PHP (>= 7.2)
-* Icinga Web 2 (>= 2.9.0)
-* Icinga Web 2 libraries:
-  * [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (>=0.11.0)
-* Icinga Web 2 modules:
-  * The `monitoring` or `icingadb` module needs to be configured and enabled.
-
-## Install the Icinga Web Jira Integration
-
-Install it [like any other module](https://icinga.com/docs/icinga-web-2/latest/doc/08-Modules/#installation).
-Use `jira` as name.
-
-## Configuration
-
-### Configuring in Web GUI
+## Configuring in Web GUI
 
 Jira allows you to configure the settings in Web GUI. Once the `jira` module has been enabled, go to its `Configuration`
 tab and configure the settings for the module as shown in the screenshot.
 
 ![Configuring in Web GUI](screenshot/configuration_page.png)
 
-### Manual Configuration
+## Manual Configuration
 
 To manually create a related configuration file, please create a dedicated module configuration directory, like:
 
@@ -78,14 +62,14 @@ afterwards:
 
     systemctl restart icinga2.service
 
-### Required Jira Custom Fields
+## Required Jira Custom Fields
 
 This module requires you to create two custom fields in Jira:
 
 * `icingaKey`: a searchable text field
 * `icingaStatus`: a short text field, 12 characters are enough
 
-### icingaKey field value
+## icingaKey field value
 
 TL;DR: you do not need to read this, it is just for those who are curios how
 this field is going to be used.
@@ -105,7 +89,7 @@ following JQL construct:
 A little bit weird, but it should work fine. And as this field is usually not
 shown anywhere, it shouldn't disturb.
 
-### Fill Jira Custom Fields
+## Fill Jira Custom Fields
 
 For your customized workflows you might need this module to ship additional
 fields. Additional Jira custom fields for the issues can either be configured in Web GUI or manually: