From 19f976f7565f6f829dfa04e38d5b5f2cf0aa9c80 Mon Sep 17 00:00:00 2001 From: Eric Sauer Date: Tue, 18 Aug 2020 14:58:26 -0400 Subject: [PATCH] Move our documentation out to readthedocs.io (#161) * Migrate to mkdocs for publishing on readthedocs * Start nav * Fixing images, links and nav * Test local linking * use page prefix on install links * Hopefully final commit with link fixes, readme and contributing update. * Fix img links on README --- docs/CONTRIBUTING.md => CONTRIBUTING.md | 0 README.md | 13 ++++------ docs/Architecture.md | 2 +- docs/Configuration.md | 4 +-- docs/Dashboards.md | 22 ++++++++--------- docs/Demo.md | 6 ++--- docs/Development.md | 20 +++++++-------- docs/Install.md | 8 +++--- .../img}/Favicon-Pelorus-favicon-32x32.png | Bin .../Icon-Pelorus-A-Standard-RGB_smaller.png | Bin .../img}/Logo-Pelorus-A-Standard-RGB.png | Bin .../Logo-Pelorus-A-Standard-RGB_smaller.png | Bin {media => docs/img}/architecture.png | Bin .../img}/exporter-relationship-diagram.png | Bin .../img}/pelorus-dashboard-first-deploy.png | Bin .../img}/pelorus-dashboard-idle-data.png | Bin .../img}/pelorus-dashboard-no-data.png | Bin .../img}/pelorus-dashboard-second-deploy.png | Bin {media => docs/img}/sdp-dashboard.png | Bin {media => docs/img}/signin.png | Bin docs/index.md | 23 ++++++++++++++++++ mkdocs.yml | 11 +++++++++ 22 files changed, 70 insertions(+), 39 deletions(-) rename docs/CONTRIBUTING.md => CONTRIBUTING.md (100%) rename {media => docs/img}/Favicon-Pelorus-favicon-32x32.png (100%) rename {media => docs/img}/Icon-Pelorus-A-Standard-RGB_smaller.png (100%) rename {media => docs/img}/Logo-Pelorus-A-Standard-RGB.png (100%) rename {media => docs/img}/Logo-Pelorus-A-Standard-RGB_smaller.png (100%) rename {media => docs/img}/architecture.png (100%) rename {media => docs/img}/exporter-relationship-diagram.png (100%) rename {media => docs/img}/pelorus-dashboard-first-deploy.png (100%) rename {media => docs/img}/pelorus-dashboard-idle-data.png (100%) rename {media => docs/img}/pelorus-dashboard-no-data.png (100%) rename {media => docs/img}/pelorus-dashboard-second-deploy.png (100%) rename {media => docs/img}/sdp-dashboard.png (100%) rename {media => docs/img}/signin.png (100%) create mode 100644 docs/index.md create mode 100644 mkdocs.yml diff --git a/docs/CONTRIBUTING.md b/CONTRIBUTING.md similarity index 100% rename from docs/CONTRIBUTING.md rename to CONTRIBUTING.md diff --git a/README.md b/README.md index df7ac01e0..b58a204cd 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -![Pelorus](media/Logo-Pelorus-A-Standard-RGB_smaller.png) +![Pelorus](docs/img/Logo-Pelorus-A-Standard-RGB_smaller.png) ![](https://github.com/redhat-cop/pelorus/workflows/Pylama/badge.svg) @@ -16,17 +16,14 @@ Currently, Pelorus functionality can capture proven metrics that measure Softwar Pelorus is a Grafana dashboard that can easily be deployed to an OpenShift cluster, and provides an organizational-level view of the [four critical measures of software delivery performance](https://blog.openshift.com/exploring-a-metrics-driven-approach-to-transformation/). -![Software Delivery Metrics Dashboard](media/sdp-dashboard.png) +![Software Delivery Metrics Dashboard](docs/img/sdp-dashboard.png) A short video describing each of these metrics is available [here](https://www.youtube.com/watch?v=7-iB_KhUaQg). -## Installation +## Documentation -A guide for installation can be found in the install document found in the [install guide](./docs/Install.md) - -## User Guide -The [Pelorus user guide](/docs/UserGuide.md) provides an index to all documentation. +Pelorus documentation is available at [pelorus.readthedocs.io](https://pelorus.readthedocs.io/). ## Contributing to Pelorus -If you are interested in contributing to the Pelorus project, please review our Contribution guide which can be found in the [contribution guide](./docs/CONTRIBUTING.md) +If you are interested in contributing to the Pelorus project, please review our Contribution guide which can be found in the [contribution guide](./CONTRIBUTING.md) diff --git a/docs/Architecture.md b/docs/Architecture.md index 637d48bc0..58babb024 100644 --- a/docs/Architecture.md +++ b/docs/Architecture.md @@ -2,7 +2,7 @@ The following diagram shows the various components and traffic flows in the Pelorus ecosystem. -![Pelorus Architecture Diagram](/media/architecture.png) +![Pelorus Architecture Diagram](img/architecture.png) Pelorus is composed of the following open source components. diff --git a/docs/Configuration.md b/docs/Configuration.md index a4778c51c..49e53b93f 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -2,7 +2,7 @@ ## Configuring The Pelorus Stack -The Pelorus stack (Prometheus, Grafana, Thanos, etc.) can be configured by changing the `values.yaml` file that is passed to helm. The recommended practice is to make a copy of the one [provided in this repo](/charts/)deploy/values.yaml), and store in in your own configuration repo for safe keeping, and updating. Once established, you can make configuration changes by updating your `values.yaml` and applying the changes like so: +The Pelorus stack (Prometheus, Grafana, Thanos, etc.) can be configured by changing the `values.yaml` file that is passed to helm. The recommended practice is to make a copy of the one [provided in this repo](https://github.com/redhat-cop/pelorus/blob/v1.2.1-rc/charts/pelorus/values.yaml), and store in in your own configuration repo for safe keeping, and updating. Once established, you can make configuration changes by updating your `values.yaml` and applying the changes like so: ``` helm upgrade pelorus charts/deploy --namespace pelorus --values myclusterconfigs/pelorus/values.yaml @@ -15,7 +15,7 @@ The following configurations may be made through the `values.yaml` file: | `openshift_prometheus_htpasswd_auth` | yes | The contents for the htpasswd file that Prometheus will use for basic authentication user. | User: `internal`, Password: `changeme` | | `openshift_prometheus_basic_auth_pass` | yes | The password that grafana will use for its Prometheus datasource. Must match the above. | `changme` | | `custom_ca` | no | Whether or not the cluster serves custom signed certificates for ingress (e.g. router certs). If `true` we will load the custom via the [certificate injection method](https://docs.openshift.com/container-platform/4.4/networking/configuring-a-custom-pki.html#certificate-injection-using-operators_configuring-a-custom-pki) | `false` | -| `extra_prometheus_hosts` | no | Configures additional prometheus instances for a multi-cluster setup. See [Deploying across multple clusters](/docs/Install.md#deploying-across-multiple-clusters) for details. | Nil | +| `extra_prometheus_hosts` | no | Configures additional prometheus instances for a multi-cluster setup. See [Deploying across multple clusters](/page/Install.md#deploying-across-multiple-clusters) for details. | Nil | | `exporters` | no | Specified which exporters to install. See [Configuring Exporters](#configuring-exporters). | Installs deploytime exporter only. | ## Configuring Exporters diff --git a/docs/Dashboards.md b/docs/Dashboards.md index 2382c66c3..d3ff80ef8 100644 --- a/docs/Dashboards.md +++ b/docs/Dashboards.md @@ -17,7 +17,7 @@ By providing data organized into collections that track organizational behaviors _Software Delivery Performance_ is a measure of an organization's ability to effectively deliver software-based products they have built to their customers. It is comprised of 4 _measures_ that provide a balanced perspective, taking both speed to market and stability measures into account. Tracking _Software Delivery Performance_ over time provides IT organizations with data they can use to make smarter investments in their internal tools and processes to optimize their delivery processes based on the types of products they are delivering. This outcomes provides a bridge between development, operations and leadership, allowing them to better communicate about whether proposed work on infrastructure imrovements or process developments are in line with the overall vision and financial goals of the organization at large. -![Software Delivery Performance dashboard](/media/sdp-dashboard.png) +![Software Delivery Performance dashboard](img/sdp-dashboard.png) The Pelorus _Software Delivery Performance_ dashboard tracks the four primary measures of software delivery: @@ -31,7 +31,7 @@ The Pelorus _Software Delivery Performance_ dashboard tracks the four primary me ### Measures -![Exporter relaionship diagram](/media/exporter-relationship-diagram.png) +![Exporter relaionship diagram](img/exporter-relationship-diagram.png) #### Lead Time for Change @@ -47,10 +47,10 @@ For an organization-level measurement, aggregate by averaging the lead time for The following exporters are required to calculate _Lead Time for Change_: -* The [commit time exporter](/exporters/committime) provides the `commit_time` metric, which is the timestamp that a commit was made to source control. -* The [deploy time exporter](/exporters/deploytime) provides the `deploy_time` metric, which is a timestamp that a production deployment was rolled out. +* The [commit time exporter](https://github.com/redhat-cop/pelorus/blob/master/exporters/committime) provides the `commit_time` metric, which is the timestamp that a commit was made to source control. +* The [deploy time exporter](https://github.com/redhat-cop/pelorus/blob/master/exporters/deploytime) provides the `deploy_time` metric, which is a timestamp that a production deployment was rolled out. -The exporters are only responsible for gathering data about individual events. Before the dashboard consumes them, we perform some aggregation calculations in a set of [PrometheusRules](/charts/deploy/templates/prometheus-rules.yaml). This converts individual `commit_time` and `deploy_time` data points into the following metrics: +The exporters are only responsible for gathering data about individual events. Before the dashboard consumes them, we perform some aggregation calculations in a set of [PrometheusRules](https://github.com/redhat-cop/pelorus/blob/master/charts/pelorus/templates/prometheus-rules.yaml). This converts individual `commit_time` and `deploy_time` data points into the following metrics: * `sdp:lead_time:by_app` - Calculated lead times by application (`deploy_time - commit_time`) * `sdp:lead_time:global` - A Global average of `sdp:lead_time:by_app` @@ -71,7 +71,7 @@ For an organization-level measurement, take the sum across product-level deploym The following exporters are required to calculate _Deployment Frequency_: -* The [deploy time exporter](/exporters/deploytime) provides the `deploy_time` metric, which is a timestamp that a production deployment was rolled out. +* The [deploy time exporter](https://github.com/redhat-cop/pelorus/blob/master/exporters/deploytime) provides the `deploy_time` metric, which is a timestamp that a production deployment was rolled out. The dashboard then just tracks a `count_over_time()` of the individual `deploy_time` metrics for the time range selected in the dashboard. It also provides a comparison to the previous time range. @@ -89,9 +89,9 @@ For an organizational-level measurement, average MTTR data across products. The following exporters are required to calculate _Mean Time to Restore_: -* The [failure exporter](/exporters/failure) provides the `failure_creation_timestamp` and `failure_resolution_timestamp` metrics, which attempt to capture the beginning and end of individual failure or degredation events in customer-facing systems. This data is typically collected from a ticketing system, though automated approaches of failure detection and tracking could be added in the future. +* The [failure exporter](https://github.com/redhat-cop/pelorus/blob/master/exporters/failure) provides the `failure_creation_timestamp` and `failure_resolution_timestamp` metrics, which attempt to capture the beginning and end of individual failure or degredation events in customer-facing systems. This data is typically collected from a ticketing system, though automated approaches of failure detection and tracking could be added in the future. -The exporters are only responsible for gathering data about individual events. Before the dashboard consumes them, we perform some aggregation calculations in a set of [PrometheusRules](/charts/deploy/templates/prometheus-rules.yaml). This converts individual `failure_creation_timestamp` and `failure_resolution_timestamp` data points into the following metrics: +The exporters are only responsible for gathering data about individual events. Before the dashboard consumes them, we perform some aggregation calculations in a set of [PrometheusRules](https://github.com/redhat-cop/pelorus/blob/master/charts/deploy/templates/prometheus-rules.yaml). This converts individual `failure_creation_timestamp` and `failure_resolution_timestamp` data points into the following metrics: * `fr:time_to_restore` - A calculated time to restore for each failure event (`failure_resolution_timestamp - failure_creation_timestamp`) * `fr:time_to_restore:global` - A global average of all `fr:time_to_restore` calculations. @@ -113,10 +113,10 @@ For an organizational-level measurement, expand the scope of the failures captur The following exporters are require to calculate _Change Failure Rate_: -* The [failure exporter](/exporters/failure) provides the `failure_creation_timestamp` metrics, which attempt to capture the beginning of individual failure or degredation events in customer-facing systems. This data is typically collected from a ticketing system, though automated approaches of failure detection and tracking could be added in the future. -* The [deploy time exporter](/exporters/deploytime) provides the `deploy_time` metric, which is a timestamp that a production deployment was rolled out. +* The [failure exporter](https://github.com/redhat-cop/pelorus/blob/master/exporters/failure) provides the `failure_creation_timestamp` metrics, which attempt to capture the beginning of individual failure or degredation events in customer-facing systems. This data is typically collected from a ticketing system, though automated approaches of failure detection and tracking could be added in the future. +* The [deploy time exporter](https://github.com/redhat-cop/pelorus/blob/master/exporters/deploytime) provides the `deploy_time` metric, which is a timestamp that a production deployment was rolled out. -The exporters are only responsible for gathering data about individual events. Before the dashboard consumes them, we perform some aggregation calculations in a set of [PrometheusRules](/charts/deploy/templates/prometheus-rules.yaml). This converts individual `failure_creation_timestamp` and `deploy_time` data points into the following metric: +The exporters are only responsible for gathering data about individual events. Before the dashboard consumes them, we perform some aggregation calculations in a set of [PrometheusRules](https://github.com/redhat-cop/pelorus/blob/master/charts/deploy/templates/prometheus-rules.yaml). This converts individual `failure_creation_timestamp` and `deploy_time` data points into the following metric: * `fr:change_failure_rate` - A ratio of the number of failed changes to the total number of changes to the system. diff --git a/docs/Demo.md b/docs/Demo.md index a86a7a2f5..12fb4a5f1 100644 --- a/docs/Demo.md +++ b/docs/Demo.md @@ -37,7 +37,7 @@ The second argument the script takes is the url of the forked repo, so for examp ## Execution An "idle" state could resemble: -![Idle-Data](../media/pelorus-dashboard-idle-data.png) +![Idle-Data](img/pelorus-dashboard-idle-data.png) Run the demo script ``` @@ -45,7 +45,7 @@ pelorus/demo/demo.sh ``` The script will start and will begin to run the ansible-applier on the path. It will attempt to install ansible-galaxy, skipping if it is, and then run the ansible-applier playbook. This will setup a build (jenkins) as well as a dev, stage and prod environment. Once jenkins has been setup, an initial run of the basic-nginx app will build and deploy. Once that is complete, the dashboard should resemble the following: -![First-Deploy-Data](../media/pelorus-dashboard-first-deploy.png) +![First-Deploy-Data](img/pelorus-dashboard-first-deploy.png) A prompt will appear on the screen waiting for user input, the user can "rerun" the script. What this will do is create a change in the index.html file, git commit and push it to the repository, then create another pipeline build. Then the second pipeline build of basic-nginx will start. Once complete, the dashboard will update again: -![Second-Deploy-Data](../media/pelorus-dashboard-second-deploy.png) +![Second-Deploy-Data](img/pelorus-dashboard-second-deploy.png) diff --git a/docs/Development.md b/docs/Development.md index be79d663d..bf3cb19f3 100644 --- a/docs/Development.md +++ b/docs/Development.md @@ -18,25 +18,25 @@ There are three main tracks of Pelorus development to consider. We use [Helm](https://helm.sh) to provide an automated deployment and configuration experience for Pelorus. We are always doing work to cover more and more complex use cases with our helm charts. In order to be able to effectively contribute to these charts, you'll need a cluster that satisfies all of the installation prerequisites for Pelorus. -See the [Install guide](/docs/Install.md) for more details on that. +See the [Install guide](/page/Install.md) for more details on that. Currently we have two charts: -1. The [operators](/charts/operators/) chart installs the community operators on which Pelorus depends. +1. The [operators](https://github.com/redhat-cop/pelorus/blob/master/charts/operators/) chart installs the community operators on which Pelorus depends. * [Prometheus Operator](https://operatorhub.io/operator/prometheus) * [Grafana Operator](https://operatorhub.io/operator/grafana-operator) -2. The [pelorus](charts/pelorus/) chart manages the Pelorus stack, which includes: +2. The [pelorus](https://github.com/redhat-cop/pelorus/blob/master/charts/pelorus/) chart manages the Pelorus stack, which includes: * Prometheus * Thanos * Grafana * A set of Grafana Dashboards and Datasources - * The Pelorus exporters, managed in an [exporter](/charts/exporter) subchart. + * The Pelorus exporters, managed in an [exporter](https://github.com/redhat-cop/pelorus/blob/master/charts/pelorus/charts/exporters) subchart. We use Helm's [chart-testing](https://github.com/helm/chart-testing) to ensure quality and consistency in the chart. When making updates to one of the charts, ensure that the chart still passes lint testing using `helm lint`. The most common linting failure is forgetting to bump the `version` field in the `Chart.yaml`. When updating the version, use the output of `git describe` to keep the versioning in line with the repo. ## Dashboard Development -We are continually doing work to enhance and bugfix the Pelorus dashboards. Doing so requires a complete Pelorus stack, including all exporters required to populate a given dashboard. See the [Dashboards](/docs/Dashboards.md) user guide for that information. +We are continually doing work to enhance and bugfix the Pelorus dashboards. Doing so requires a complete Pelorus stack, including all exporters required to populate a given dashboard. See the [Dashboards](/page/Dashboards.md) user guide for that information. To effectively do dashboard development, you'll likely need at least two browser windows open, one with Grafana, and another with Prometheus for testing queries. Since our dashboards are imported to Grafana via the Grafana Operator, they get imported in read-only mode. Because of this, you'll need to make a copy of it for development purposes. @@ -45,7 +45,7 @@ The following outlines a workflow for working on a dashboard: 1. Sign in to Grafana via the Grafana route. 1. Once signed in, sign as an administrator 1. Click the signin button in the bottom right corner - ![Signin button](/media/signin.png) + ![Signin button](img/signin.png) 1. The admin credentials can be pulled from the following commands: ``` oc get secrets -n pelorus grafana-admin-credentials -o jsonpath='{.data.GF_SECURITY_ADMIN_USER}' | base64 -d @@ -122,7 +122,7 @@ Running an exporter on your local machine should follow this process: pip install -r exporters/requirements.txt -1. Set any environment variables required (or desired) for the given exporter (see [Configuring Exporters](docs/Configuration.md#configuring-exporters) to see supported variables). +1. Set any environment variables required (or desired) for the given exporter (see [Configuring Exporters](/page/Configuration.md#configuring-exporters) to see supported variables). 1. Start the exporter @@ -209,7 +209,7 @@ The following are notes and general steps for testing Pull Requests for specific git fetch themoosman git checkout themoosman/feature-branch ``` -2. [Install Pelorus](/docs/Install.md) from checked out fork/branch. +2. [Install Pelorus](/page/Install.md) from checked out fork/branch. >:mag: **Note**
>:mag: In most cases you can deploy changes to an existing deployment to retain existing data. 3. Log into Grafana via the grafana route. @@ -230,7 +230,7 @@ Most exporter changes can be tested locally. git fetch themoosman git checkout themoosman/feature-branch ``` -1. Gather necessary [configuration information](/docs/Configuration.md#configuring-exporters). +1. Gather necessary [configuration information](/page/Configuration.md#configuring-exporters). 1. [Run exporter localy](#running-locally). You can do this either via the command line, or use the provided [VSCode debug confuration](#ide-setup-vscode) to run it in your IDE Debugger. 1. Once exporter is running, you can test it via a simple `curl localhost:8080`. You should be validating that: 1. You get a valid response with metrics. @@ -238,7 +238,7 @@ Most exporter changes can be tested locally. ### Helm Install changes -For testing changes to the helm chart, you should just follow the [standard install process](/docs/Install.md), then verify that: +For testing changes to the helm chart, you should just follow the [standard install process](/page/Install.md), then verify that: * All expected pods are running and healthy * Any expected behavior changes mentioned in the PR can be observed. diff --git a/docs/Install.md b/docs/Install.md index a8c9cbd59..a640a99a2 100644 --- a/docs/Install.md +++ b/docs/Install.md @@ -34,19 +34,19 @@ In a few seconds, you will see a number of resourced get created. The above comm * A `Grafana` instance * A `ServiceMonitor` instance for scraping the Pelorus exporters. * A `GrafanaDatasource` pointing to Prometheus. - * A set of `GrafanaDashboards`. See the [dashboards documentation](/docs/Dashboards.md) for more details. + * A set of `GrafanaDashboards`. See the [dashboards documentation](/page/Dashboards/) for more details. * The following exporters: * Deploy Time From here, some additional configuration is required in order to deploy other exporters, and make the Pelorus -See the [Configuration Guide](/docs/Configuration.md) for more information on exporters. +See the [Configuration Guide](/page/Configuration) for more information on exporters. You may additionally want to enabled other features for the core stack. Read on to understand those options. ## Customizing Pelorus -See [Configuring the Pelorus Stack](/docs/Configuration.md) for a full readout of all possible configuration items. The following sections describe the most common supported customizations that can be made to a Pelorus deployment. +See [Configuring the Pelorus Stack](/page/Configuration) for a full readout of all possible configuration items. The following sections describe the most common supported customizations that can be made to a Pelorus deployment. ### Configure Long Term Storage (Recommended) @@ -73,7 +73,7 @@ Then pass this to runhelm.sh like this: helm upgrade pelorus charts/deploy --namespace pelorus --values values.yaml ``` -If you don't have an object storage provider, we recommend [MinIO](https://min.io/) as a free, open source option. You can follow our [MinIO quickstart](/docs/MinIO.md) to host an instance on OpenShift and configure Pelorus to use it. +If you don't have an object storage provider, we recommend [MinIO](https://min.io/) as a free, open source option. You can follow our [MinIO quickstart](/page/MinIO) to host an instance on OpenShift and configure Pelorus to use it. ### Deploying Across Multiple Clusters diff --git a/media/Favicon-Pelorus-favicon-32x32.png b/docs/img/Favicon-Pelorus-favicon-32x32.png similarity index 100% rename from media/Favicon-Pelorus-favicon-32x32.png rename to docs/img/Favicon-Pelorus-favicon-32x32.png diff --git a/media/Icon-Pelorus-A-Standard-RGB_smaller.png b/docs/img/Icon-Pelorus-A-Standard-RGB_smaller.png similarity index 100% rename from media/Icon-Pelorus-A-Standard-RGB_smaller.png rename to docs/img/Icon-Pelorus-A-Standard-RGB_smaller.png diff --git a/media/Logo-Pelorus-A-Standard-RGB.png b/docs/img/Logo-Pelorus-A-Standard-RGB.png similarity index 100% rename from media/Logo-Pelorus-A-Standard-RGB.png rename to docs/img/Logo-Pelorus-A-Standard-RGB.png diff --git a/media/Logo-Pelorus-A-Standard-RGB_smaller.png b/docs/img/Logo-Pelorus-A-Standard-RGB_smaller.png similarity index 100% rename from media/Logo-Pelorus-A-Standard-RGB_smaller.png rename to docs/img/Logo-Pelorus-A-Standard-RGB_smaller.png diff --git a/media/architecture.png b/docs/img/architecture.png similarity index 100% rename from media/architecture.png rename to docs/img/architecture.png diff --git a/media/exporter-relationship-diagram.png b/docs/img/exporter-relationship-diagram.png similarity index 100% rename from media/exporter-relationship-diagram.png rename to docs/img/exporter-relationship-diagram.png diff --git a/media/pelorus-dashboard-first-deploy.png b/docs/img/pelorus-dashboard-first-deploy.png similarity index 100% rename from media/pelorus-dashboard-first-deploy.png rename to docs/img/pelorus-dashboard-first-deploy.png diff --git a/media/pelorus-dashboard-idle-data.png b/docs/img/pelorus-dashboard-idle-data.png similarity index 100% rename from media/pelorus-dashboard-idle-data.png rename to docs/img/pelorus-dashboard-idle-data.png diff --git a/media/pelorus-dashboard-no-data.png b/docs/img/pelorus-dashboard-no-data.png similarity index 100% rename from media/pelorus-dashboard-no-data.png rename to docs/img/pelorus-dashboard-no-data.png diff --git a/media/pelorus-dashboard-second-deploy.png b/docs/img/pelorus-dashboard-second-deploy.png similarity index 100% rename from media/pelorus-dashboard-second-deploy.png rename to docs/img/pelorus-dashboard-second-deploy.png diff --git a/media/sdp-dashboard.png b/docs/img/sdp-dashboard.png similarity index 100% rename from media/sdp-dashboard.png rename to docs/img/sdp-dashboard.png diff --git a/media/signin.png b/docs/img/signin.png similarity index 100% rename from media/signin.png rename to docs/img/signin.png diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..974e60047 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,23 @@ +# Welcome to Pelorus + +![Pelorus](img/Logo-Pelorus-A-Standard-RGB_smaller.png) + +![](https://github.com/redhat-cop/pelorus/workflows/Pylama/badge.svg) + +Pelorus is a tool that helps IT organizations measure their impact on the overall performance of their organization. It does this by gathering metrics about team and organizational behaviors over time in some key areas of IT that have been shown to impact the value they deliver to the organization as a whole. Some of the key outcomes Pelorus can focus on are: + +- Software Delivery Performance +- Product Quality and Sustainability +- Customer experience + +For more background on the project you can read @trevorquinn's blog post on [Metrics Driven Transformation](https://www.openshift.com/blog/exploring-a-metrics-driven-approach-to-transformation) + +## Software Delivery Performance as an outcome + +Currently, Pelorus functionality can capture proven metrics that measure Software Delivery Performance -- a significant outcome that IT organizations aim to deliver. + +Pelorus is a Grafana dashboard that can easily be deployed to an OpenShift cluster, and provides an organizational-level view of the [four critical measures of software delivery performance](https://blog.openshift.com/exploring-a-metrics-driven-approach-to-transformation/). + +![Software Delivery Metrics Dashboard](img/sdp-dashboard.png) + +A short video describing each of these metrics is available [here](https://www.youtube.com/watch?v=7-iB_KhUaQg). diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..4c00290cc --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,11 @@ +site_name: Pelorus Documentation +theme: readthedocs +nav: + - Main: index.md + - Architecture: Architecture.md + - Installation: Install.md + - Quickstart: Demo.md + - Configuration: Configuration.md + - Using Pelorus: Dashboards.md + - Dev Guide: Development.md + \ No newline at end of file