Merge pull request #382 from Boavizta/doc-updates

chore(doc): update docs and add link checker
Boavizta · Nov 15, 2023 · dcda977 · dcda977
2 parents 26e03a4 + d312a21
commit dcda977
Show file tree

Hide file tree

Showing 8 changed files with 31 additions and 22 deletions.
diff --git a/docs/book.toml b/docs/book.toml
@@ -7,7 +7,7 @@ title = "Boavizta cloud scanner 📡"
 
 # Deactivate link checker by default
 # cargo install mdbook-linkcheck
-# [output.linkcheck]
+[output.linkcheck]
 
 [output.html]
 #theme = "my-theme"

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -7,6 +7,11 @@
 - [Quickstart - using cargo 🦀](tutorials/quickstart-rust-cli.md)
 - [Quickstart as serverless ⚡](tutorials/quickstart-serverless.md)
 
+# Explanations
+
+- [Methodology](explanations/methodology.md)
+- [How we process workload](explanations/processing-workload.md)
+
 # How-to guides
 
 - [Building CLI](how-to/building-cli.md)
@@ -16,8 +21,6 @@
 - [Setup monitoring dashboard](how-to/set-up-dashboard.md)
 - [Filtering by tags](how-to/filter-by-tags.md)
 - [Using a private instance of Boavizta API](how-to/using-private-boaviztapi.md)
-- [Source of data](explanations/source-of-data.md)
-- [How we process workload](explanations/processing-workload.md)
 
 # Reference
 

diff --git a/docs/src/explanations/methodology.md b/docs/src/explanations/methodology.md
@@ -0,0 +1,16 @@
+# Methodology and source of data
+
+Cloud scanner uses the Boavizta methodology to estimate the impacts of cloud resources.
+
+The methodology of Boavizta is described in [Digital &amp; environment : How to evaluate server manufacturing footprint, beyond greenhouse gas emissions? | Boavizta](https://boavizta.org/en/blog/empreinte-de-la-fabrication-d-un-serveur)
+
+Impact data is retrieved from [BOAVIZTA reference data API](https://github.com/Boavizta/boaviztapi/) v1.0.x.
+
+The results are similar to what you can visualize in [Datavizta](http://datavizta.boavizta.org/cloudimpact), but with automated inventory.
+
+⚠ Cloud scanner **underestimate the impacts of the cloud resources**. Because it only considers the _instances_ and _block storage_ a lot of impacts (network, potential redundancy, cloud control plan) are not included in the estimation.
+
+See also [other limits](../reference/limits.md).
+
+- https://www.boavizta.org/en
+- https://boavizta.org/en/blog/empreinte-de-la-fabrication-d-un-serveur
diff --git a/docs/src/explanations/source-of-data.md b/docs/src/explanations/source-of-data.md
diff --git a/docs/src/reference/limits.md b/docs/src/reference/limits.md
@@ -47,7 +47,7 @@ Carbon intensity of electricity is not (yet) real time. It uses and yearly extra
 
 ### Allocation of manufacture impacts
 
-Today, cloud scanner returns the manufacture impacts of a resource corresponding to _the entire lifecycle_ of the ressource. The manufacture impacts returned for a VM are the same if you use it one hours or several year. Said differently we do _not_ amortize the manufacturing impacts over the duration of use.
+Today, cloud scanner returns the manufacture impacts of a resource corresponding to _the entire lifecycle_ of the ressource. The manufacture impacts returned for a VM are the same if you use it one hours or several year. To say it differently, we do _not_ amortize the manufacturing impacts over the duration of use.
 
 ### We do not provide margins of error
 

diff --git a/docs/src/reference/source-of-data.md b/docs/src/reference/source-of-data.md
diff --git a/docs/src/reference/testing.md b/docs/src/reference/testing.md
@@ -1,8 +1,8 @@
 # Testing
 
-Whne launched with `cargo test -- --include-ignored` some the unit tests require a specific instance to run (when launched ).
+When launched with `cargo test -- --include-ignored` some the unit tests require a specific instance to run (when launched ).
 
-> These integration tests requiere specific instance to be up and running to pass. This means they are tied to a specific cloud account.
+> These integration tests require specific instances to be up and running to pass. This means they are tied to a specific cloud account.
 
 Commands to start or stop instances:
 

diff --git a/docs/src/tutorials/quickstart-dashboard-docker.md b/docs/src/tutorials/quickstart-dashboard-docker.md
@@ -1,8 +1,10 @@
 # Quick start : display dashboard using docker-compose 🐳
 
-No installation needed, you will run a public docker image of cloud-scanner CLI and Boavizta API.
+Visualize the live impacts of you account in a dashboard.
 
-All data remain local (this docker-compose stack uses a _private instance_ of Boavizta API).
+No installation needed, you will run a public docker image of cloud-scanner CLI, Boavizta API, Prometheus and Grafana to get access to a demo dashboard..
+
+All data remain will  local to your environment (this docker-compose stack uses a _private instance_ of Boavizta API).
 
 ## Pre-requisites
 
@@ -31,6 +33,6 @@ docker-compose up
 - ⚠ This docker-compose example is **not** intended  for production deployment, but rather for quick testing.
   - ports of all services are exposed.
   - Grafana is served on http with default login.
-- You may have to update the line mapping your AWS profile (Replace `AWS_PROFILE=${AWS_PROFILE}` by `AWS_PROFILE=the-real-name-of-your-profile`).
+- You may have to update the line mapping your AWS profile (Replace `AWS_PROFILE=${AWS_PROFILE}` by `AWS_PROFILE=the-real-name-of-your-profile`) when using Podman. It seems that Podman compose does not map the variables of the environment to the containers.
 - In corporate environments, you may need to provide your certificates authorities certificates (`ca-certificates`) to the cloud-scanner container (uncomment the mapping line in the docker-compose file).
-- For the demo, we deliberately set a short metrics scrapping interval (30 seconds in this demo). In production deloymnent, you may want to increase this metric scraping interval in the prometheus configuration file.
+- For the demo, we deliberately set a short metrics scrapping interval (30 seconds). In a production environment, you may want to increase this metric scraping interval to reduce the API calls and volume of data. This scrapping period is set in the Prometheus configuration file.