Merge branch 'main' into acramsay/issue18

Makefile

@@ -10,11 +10,11 @@ build: poetry-install
 	poetry run mkdocs build
 
 .PHONY: serve
-serve: 
+serve: poetry-install
 	poetry run mkdocs serve
 
-.PHONY: install-deps
-install-deps:
+.PHONY: brew
+brew:
 	brew bundle --force
 
 .PHONY: backstage

README.md

@@ -1,25 +1,47 @@
 # openo11y.dev
 
-Welcome to Open O11y! This repository hosts the website files for [openo11y.dev](https://openo11y.dev), an open-source public website with guidance and information on observability (o11y).
+Welcome to OpenO11y! This repository hosts the website files for
+[openo11y.dev](https://openo11y.dev), an open-source public website dedicated
+to providing guidance and resources on observability (o11y).
 
-If you're looking to contribute, please see the [contributing](./docs/contributing.md) documentation.
+If you're looking to contribute, please see the
+[contributing](./docs/contributing.md) documentation.
 
 ## Local Development
 
-### MkDocs
+### Prerequisites
 
-The site is built using `mkdocs`. You can serve the site locally by running
+The following tools will need to be installed:
 
-```sh
-make install-deps
-make build
-make serve
-```
+- [Make](https://www.gnu.org/software/make/): A build automation tool.
+- [Python](https://www.python.org/downloads/): The programming language used
+  for development.
+- [Poetry](https://python-poetry.org/docs/#installation): A tool for dependency
+  management in Python.
+
+Note: OSX users with [Homebrew](https://brew.sh/) installed can install Poetry
+by running the command `make brew`.
+
+### Working on Documentation
+
+Our site is built using [mkdocs](https://www.mkdocs.org/), a static site
+generator optimized for project documentation. It features hot reloading,
+allowing immediate preview of changes, and can compile documentation into
+static assets for deployment.
+
+To work on the documentation:
+
+- Use `make serve` to start a local server. Your changes can be viewed in
+  real-time at http://127.0.0.1:8000.
+- To build the documentation, run `make build`. This command generates static
+  files and stores them in the `./site` directory.
 
 ## Contributing
 
 - Follow the guidelines established in [CONTRIBUTING.md](docs/CONTRIBUTING.md)
-- Images should be placed under the root `img` folder and referred to using HTML `<img>` tags
+- Images should be placed under the root `img` folder and referred to using
+  HTML `<img>` tags
 - H3 header (`###`) should be the default header within a page
-- H2 header (`##`) will appear in the navigation as the page's table of contents
+- H2 header (`##`) will appear in the navigation as the page's table of
+  contents
 - make sure to add to _sidebar

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.

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/)

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":