feat: update welcome page and narrow down content (#37)

--------- Co-authored-by: Adriel Perkins <[email protected]> Co-authored-by: Casey Wilson <[email protected]> Co-authored-by: Adriel Perkins <[email protected]>
liatrio · Feb 9, 2024 · 6dc4bab · 6dc4bab
1 parent 8f36094
commit 6dc4bab
Show file tree

Hide file tree

Showing 5 changed files with 31 additions and 37 deletions.
diff --git a/.markdownlint.yaml b/.markdownlint.yaml
@@ -0,0 +1,5 @@
+MD007:
+  # Spaces for indent
+  indent: 4
+MD013:
+  line_length: 90
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -1,13 +1,13 @@
-# Contributing to open o11y
+# Contributing to OpenO11y
 
-Anyone is welcome to contribute to open o11y, and there's a few major
+Anyone is welcome to contribute to OpenO11y, and there's a few major
 aspects of this project to which one can contribute.
 This guide will help you understand how our project works and how you can contribute effectively.
 If you have any questions that aren't answered in this guide, please feel free to reach out on our [Slack Team](https://liatrio.slack.com/archives/C04KGSFF407).
 
 ## Table of Contents
 
-- [Contributing to open o11y](#contributing-to-open-o11y)
+- [Contributing to OpenO11y](#contributing-to-open-o11y)
   - [Table of Contents](#table-of-contents)
   - [Getting Started](#getting-started)
   - [Github Repositories](#github-repositories)
@@ -25,7 +25,7 @@ Details can be found in our [README.md](https://github.com/liatrio/openo11y.dev/
 ## Github Repositories
 
 The following is a list of repositories that relate or are actively being developed as part
-of **open o11y**.
+of **OpenO11y**.
 
 - [o11y-platform-deployment](https://github.com/liatrio/o11y-platform-deployment) #[branch] Terragrunt deployment repo for the o11y platform
 - [aws-managed-service-module](https://github.com/liatrio/aws-managed-services) #[branch] TF module for managed services in AWS for o11y

diff --git a/docs/human-systems/observing-human-systems.md b/docs/human-systems/observing-human-systems.md
@@ -2,7 +2,7 @@
 
 ## RFC 2119
 
-Open O11y has very strong opinions on how to observe human systems ethically. While
+OpenO11y has very strong opinions on how to observe human systems ethically. While
 acknowledging it is social advice, this guidance is considered a specification. Thus, we
 use certain keywords in accordance with [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
 
@@ -11,7 +11,7 @@ use certain keywords in accordance with [RFC 2119](https://www.ietf.org/rfc/rfc2
 Many of us typically think of Observability in the context of observing a system of
 software (e.g. a collection of microservices that form a single product). Some of the
 advice provided herein describes how to observe human systems like teams or development
-organizations. This is a much more sensitive activity. Open O11y offers these guiding
+organizations. This is a much more sensitive activity. OpenO11y offers these guiding
 principles to observing human systems ethically.
 
 1. When observing human systems, individuals ***MUST*** feel and be safe while being
@@ -23,7 +23,7 @@ principles to observing human systems ethically.
 4. The gathering and use of telemetry ***MUST*** be excessively transparent[^1] to all
   human systems impacted by the telemetry.
 5. Human evaluations and compensation ***MUST NOT*** rely on the telemetry data listed
-  within Open o11y.
+  within OpenO11y.
 6. When observing human systems, observers ***MUST*** continuously reevaluate the health
   and safety of the people and culture.
 7. Secondary contributors ***MUST NOT*** use telemetry to measure the teams they support
@@ -100,7 +100,7 @@ engineering principles.
 
 ### Secondary Contributors
 
-Open O11y uses this term to describe roles that exist to organize, improve, or facilitate
+OpenO11y uses this term to describe roles that exist to organize, improve, or facilitate
 the work of others. In the world of software development, these roles commonly include,
 but are not limited to, SCRUM Masters, Project Managers, Product Owners, and Management.
 Secondary contributors ***SHOULD NOT*** use telemetry to observe the teams they support.

diff --git a/docs/index.md b/docs/index.md
@@ -1,48 +1,37 @@
-# Open O11y
+# OpenO11y
 
 ---
 
-*To improve, you must observe. Developed by an Observability Technical Advisory Group (TAG) at [Liatrio](https://www.liatrio.com/), Open O11y is a set of documentation, references, and guidance focused on observability.  Open O11y is guided by a singular north star, enabling observability everywhere.*
+*To improve, you must observe. OpenO11y is a set of documentation, reference
+architectures, and guidance focused on observability. OpenO11y is focused on enabling
+wider Observability adoption through its written contributions.*
 
 ---
 
 ## What is o11y?
 
-> **o11y** - shorthand for *observability*[^1]  which is the ability to measure the
+> **o11y** - shorthand for *observability*[^1] which is the ability to measure the
 > internal states of a system by examining its outputs[^2].
 
-O11y empowers organizations to easily and effectively observe key data at scale;
-enabling decision making in order to improve company culture, security, effectiveness,
-growth, and ultimate business success.
-
-Just as it's important to define what o11y is, it's also important to define a system.
+Observability empowers organizations to easily and effectively observe key data at scale;
+enabling decision making in order to improve the organization's culture, security,
+effectiveness, growth, and ultimate success.
 
 > **system** - a group of interacting, interrelated, or interdependent elements
 > forming a complex whole
 
-O11y is focused on systems, and systems can be your microservices, or your people,
-your teams, your company and organization.
-
-With that in mind, our goal is to help enable everyone in the industry observe their systems.
-
-## How do we do this?
+Observability is focused on systems. Systems can be comprised of software, such as a
+system of microservices. However, systems can also have other compositions such as people
+forming a team, a group of teams, an entire organization, etc.
 
-Here's some things you'll find through Open O11y that help achieve this goal:
+## Mission
 
-- Contributions to Open Source communities focused on O11y
-  - For example: [Open Telemetry](https://opentelemetry.io/)
-- Open-source automations published to get organizations and teams started quickly
-  - For example: An observability stack deployable in AWS
-  - Guidance on how to use those automations & scale
-- Guidance on how to leverage metrics and what to observe related to:
-  - team effectiveness
-  - joy
-  - security
-
-Just like security, o11y is a team sport. We've helped many clients implement
-and improve their observability practices, and we want to bring those contributions
-to everyone.
+As an [open source project](https://github.com/liatrio/openo11y.dev), OpenO11y's mission
+is to enable everyone to observe and improve their systems by offering socio-technical[^3]
+guidance, reference architectures (coming soon!), tooling recommendations, and demos.
 
 [^1]: [numeronym](https://en.wikipedia.org/wiki/Numeronym)
 
 [^2]: [What is Observability - Splunk](https://www.splunk.com/en_us/data-insider/what-is-observability.html)
+
+[^3]: [Socio-Technical Theory](https://open.ncl.ac.uk/theories/9/socio-technical-theory/)
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -61,7 +61,7 @@ repo_url: https://github.com/liatrio/openo11y.dev
 site_url: https://openo11y.dev
 
 nav:
-  - "Welcome to Open O11y": "index.md"
+  - "Welcome to OpenO11y": "index.md"
   - "Why Metrics Matter": "./why-metrics-matter.md"
   - "Guidance":
     - "Human Systems":