pagerduty / operational-review-docs

PagerDuty's public operational review documentation.

PagerDuty Operational Review Documentation

This is a public version of the Operational Review framework that PagerDuty is adapting and implementing internally. It is used to ensure that PagerDuty leadership is aligned on the impact that real-time, digital operations have on our business outcomes. See the About page for more information.

You can view the documentation directly in this repository, or rendered as a website at https://reviews.pagerduty.com.

Development

We use MkDocs to create a static site from this repository.

Native

For local development on your native device,

1. Install MkDocs. pip install mkdocs
2. Install MkDocs PyMdown Extensions. pip install pymdown-extensions
3. Install Pygments if you want syntax highlighting for any code examples. pip install pygments
4. Install the PagerDuty MkDocs Theme.
   1. git clone https://github.com/pagerduty/mkdocs-theme-pagerduty
   2. cd mkdocs-theme-pagerduty & python3 setup.py install
5. To test locally, run mkdocs serve from the project directory.
6. You can now view the website in your browser at http://127.0.0.1:8000. The site will automatically update as you edit the code.

Docker

For local development using Docker,

1. Build the docker image and load it for immediate use. docker build --load -t mkdocs .
2. Run the container and pass through your current working directory. docker run -v $(pwd):/docs -p 127.0.0.1:8000:8000 mkdocs
3. You can now view the website in your browser at http://127.0.0.1:8000. The site will automatically update as you edit the code.

Note: If you're using an Apple Silicon device, add --platform linux/arm64/v8 to the docker build command to get a native Apple Silicon image. That will work faster than translating an arm64 image.

Deploying

1. Run mkdocs build --clean to produce the static site for upload.

2. Upload the site directory to S3 (or wherever you would like it to be hosted).

    aws s3 sync ./site/ s3://[BUCKET_NAME] \
      --acl public-read \
      --exclude "*.py*" \
      --delete
   

License

Apache 2 (See LICENSE file)

Contributing

Thank you for considering contributing! If you have any questions, just ask - or submit your issue or pull request anyway. The worst that can happen is we'll politely ask you to change something. We appreciate all friendly contributions.

Here is our preferred process for submitting a pull request,

1. Fork it ( https://github.com/PagerDuty/operational-review-docs/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request.

operational-review-docs's Issues

Typo on introduction.md

... is spent on digital transformation initiatives[].

This may be a typo of a link.

operational-review-docs/docs/introduction.md

Line 8 in 3b552eb

Operational maturity doesn’t happen overnight—it takes continued commitment, focus, learning, and practice. According to IDC, on average, 3.7% of an enterprise organization’s revenue is spent on digital transformation initiatives[]. The goals of transformation initiatives typically include outcomes like [achieving greater profitability and market share](https://services.google.com/fh/files/misc/state-of-devops-2019.pdf) by becoming a faster, more nimble, and more secure organization that can better serve the needs of demanding customers in today’s competitive marketplace. To achieve that, organizational transformation initiatives typically require very large investments, long-term strategy, and executive support.