Add pipeline documentation (#36522)

Co-authored-by: Grace Park <gracepark@github.com>

src/github-apps/README.md

@@ -1,11 +1,56 @@
-# GitHub Apps
+# GitHub Apps pipeline
 
-Our GitHub Apps pipeline adds automated documentation for GitHub Apps.
+Our GitHub Apps pipeline creates autogenerated documentation for docs.github.com from the OpenAPI stored in the open-source repository [`github/rest-api-description`](https://github.com/github/rest-api-description).
 
-## What is GitHub Apps
-
-GitHub Apps is a GitHub product that allows custom applications to respond to events on GitHub.
+The pipeline is used to generate data that is used by the docs.github.com site when deployed locally, in preview environments, or in production.
 
 ## How does it work
 
+![A flow chart describing how the automation pipeline for GitHub Apps generates documentation](./github-apps-pipeline-flowchart.png)
+
+A [workflow](.github/workflows/sync-openapi.yml) is used to trigger the automation of the GitHub Apps documentation. The workflow runs automatically on a schedule. The workflow that triggers the GitHub Apps pipeline also triggers other automation pipelines that use the OpenAPI as the source data:
+- GitHub Apps
+- REST
+- Webhooks
+
+The workflow automatically creates a pull request with the changes (for all three pipelines) and the label `github-openapi-bot`.
+
+The workflow runs the `src/rest/scripts/update-files.js` script.
+
+## Local development
+
+To run the GitHub Apps pipeline locally:
+
+1. Clone the [`github/rest-api-description`](https://github.com/github/rest-api-description) repository inside your local `docs-internal` repository. 
+1. Run `src/rest/scripts/update-files.js -s rest-api-description -o github-apps`.
+
+## About this directory
+
+- `src/rest/data` - The automatically generated data files created by running this pipeline.
+- `src/rest/lib` - The source code used in production for the automated documentation generated by the GitHub Apps pipeline and configuration files edited by content and engineering team members.
+  - `src/rest/lib/config.json` - A configuration file used to specify metadata about the GitHub Apps pipeline. This file contains the SHA of the commit in `github/rest-api-description` that was used to generate the data in `src/github-apps/data`. This value is automatically updated when the pipeline runs.
+- `src/rest/scripts` - The scripts and source code used run the GitHub Apps pipeline, which updates the `src/github-apps/data` directory. 
+- `src/rest/tests` - The tests used to verify the GitHub Apps pipeline.
+
+## Configuring the pipeline
+
+The `src/github-apps/lib/config.json` file can contain any metadata needed by the content and engineering teams to configure the webhooks pipeline. The file currently only contains the following property:
+
+- `sha` - The SHA of the commit in `github/rest-api-description` that was used to generate the data in `src/github-apps/data`. This value is automatically updated when the pipeline runs.
+
+## Content team
+
+The content writers can manually update parts of the autogenerated Markdown file `content/rest/overview/endpoints-available-for-github-apps.md`. All frontmatter properties except `versions` can be manually modified and will not be overwritten on subsequent runs of the pipeline. The pipeline does update the `versions` property on each run.
+
+Writers can also add an introduction paragraph _above_ the following Markdown comment:
+
+```markdown
+<!-- Content after this section is automatically generated -->
+```
+
 ## How to get help
+
+Slack: `#docs-engineering`
+Repo: `github/docs-engineering`
+
+If you have a question about the GitHub Apps pipeline, you can ask in the `#docs-engineering` Slack channel. If you notice a problem with the GitHub Apps pipeline, you can open an issue in the `github/docs-engineering` repository.