add configure, contribution, and migration guides

docs/source/configure/index.md

@@ -0,0 +1,4 @@
+---
+title: Configure Elastic Docs
+navigation_title: Configuration reference
+---

docs/source/configure/page-level.md

@@ -0,0 +1,4 @@
+---
+title: Page configuration
+navigation_title: Page
+---

docs/source/configure/site-level.md

@@ -0,0 +1,18 @@
+---
+title: Site configuration
+navigation_title: Site
+---
+
+Start by understanding how the new V3 system works at the site level compared to how our custom AsciiDoctor system works. The system consists of:
+
+
+| System property | Asciidoc | V3 |
+| -------------------- | -------------------- | -------------------- |
+| **Content sources** --> Collections of markup files containing doc content. These are split up across many docs repos. | _Books_ | _Content sets_ |
+| **Content configuration** --> A way to specify where to find those content sources, and in what order they should be added to the site. | Configuration file ([`conf.yml`](https://github.com/elastic/docs/blob/master/conf.yaml) in elastic/docs) | Config file location TBD |
+| **Cross-site values** --> Key-value pairs that should be substituted across all sources as web pages are built. | Shared attributes ([`shared/`](https://github.com/elastic/docs/tree/master/shared) in elastic/docs) | Shared attrs file TBD |
+| **Docs build tool** --> An engine used to take the markup in the content sources and transform it into web pages. | Customized version of AsciiDoctor (lives in [**elastic/docs**](https://github.com/elastic/docs)) | Customized doc builder using open source tools (lives in [**elastic/docs-builder**](https://github.com/elastic/docs-builder)) |
+
+## Asciidoc
+
+![site-level config in the asciidoc system](./img/site-level-asciidoctor.png)

docs/source/contribute/change-browser.md

@@ -0,0 +1,11 @@
+---
+title: Update the docs locally
+---
+
+1. Install dependencies
+2. Clone repositories
+3. Make changes
+4. Open a Pull Request
+5. Work with CI
+6. Get approvals and merge
+7. View your changes live on elastic.co

docs/source/contribute/change-local.md

@@ -0,0 +1,3 @@
+---
+title: Update the docs in your web browser
+---

docs/source/contribute/index.md

@@ -3,12 +3,8 @@ title: Elastic Docs contribution guide
 navigation_title: Contribution guide
 ---
 
-Want to contribute to the Elastic documentation? You're in the right spot!
+Want to contribute to the Elastic documentation? You're in the right spot! Select an option below to get started:
 
-1. Install dependencies
-2. Clone repositories
-3. Make changes
-4. Open a Pull Request
-5. Work with CI
-6. Get approvals and merge
-7. View your changes live on elastic.co
+* I just want to suggest a change --> [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml)
+* I want to make a small change to a single page --> [Update the docs in your _web browser_](change-browser.md).
+* I want to make a larger change or a change to multiple pages --> [Update the docs in your _code editor_](change-local.md).

docs/source/docset.yml

@@ -22,9 +22,17 @@ toc:
   - folder: migration
     children:
       - file: index.md
+      - file: file-structure.md
   - folder: contribute
     children:
       - file: index.md
+      - file: change-browser.md
+      - file: change-local.md
+  - folder: configure
+    children:
+      - file: index.md
+      - file: page-level.md
+      - file: site-level.md
   - folder: syntax
     children:
       - file: index.md

docs/source/migration/file-structure.md

@@ -0,0 +1,61 @@
+---
+title: File structure
+---
+
+In both the AsciiDoc- and V3-based systems, file structure is largely independent from the resulting site navigation.
+
+## File and directory structure
+
+AsciiDoc files and assets (like images and videos) can be stored anywhere within the directories provided as `sources` for a given book in the central [`config.yaml` file in the /docs repo](https://github.com/elastic/docs/blob/master/conf.yaml).
+
+## Migration tool output
+
+The migration tool will add all MD files in a single directory. There will be one MD file for each web page in the migrated book. The name of each MD file and the URL in the new docs system are both derived from the URL of the AsciiDoc-built page.
+
+**Example:** Here's what happens with the
+[Spans](https://www.elastic.co/guide/en/apm/guide/current/data-model-spans.html) page
+in the APM docs:
+
+* **Old URL**: The URL for the page in the old system is:
+  `https://www.elastic.co/guide/en/apm/guide/current/data-model-spans.html`.
+  From the URL, we can determine the:
+    * _base URL_: `https://www.elastic.co/guide`
+    * _book ID_: `en/apm/guide`
+    * _version_: `current`
+    * _page ID_: `data-model-spans`
+* **New filename**: The page ID determines the filename of the migrated MD file:
+% `data-model-spans.mdx`. This file will be in the root directory of the directory containing the content for the `en/apm/guide` book.
+* **New URL**: The new URL for this page in the new docs system will be `xxxx`.
+*
+Because a single AsciiDoc file can contain the content for multiple pages (or content
+displayed on a single page could be spread across multiple AsciiDoc files), the `.asciidoc`
+filename can be different than the `.md` filename. However, you should be able to locate
+the source content if you know which web page it lives on.
+
+In the output from the migration tool the slug (for example, `en/apm/guide/data-model-spans`)
+and the MD filename (for example, `data-model-spans.md`) are both derived from
+the page ID, they don't _have_ to be the same.
+
+### Assets
+
+The migration tool creates an `images/` directory in the base directory for the doc set.
+Inside the `images/` directory, there is subdirectory for each page ID that contains images.
+
+For example, the images that are used on the [Entity Analytics dashboard](https://www.elastic.co/guide/en/security/current/detection-entity-dashboard.html) page in the AsciiDoc Security book would be copied to
+the following location in the migrated docs:
+
+```
+images
+  └─ detection-entity-dashboard
+      ├─ dashboards-anomalies-table.png
+      ├─ dashboards-entity-dashboard.png
+      ├─ dashboards-host-score-data.png
+      ├─ dashboards-run-job.png
+      └─ dashboards-user-score-data.png
+```
+
+These can be reorganized post-migration.
+
+### Reusable content
+
+Reusable content is lost during migration.