From 0439e9c0b081699e13b2c2120a7c0b1ef0c87bcd Mon Sep 17 00:00:00 2001 From: George Wallace Date: Tue, 18 Mar 2025 14:56:40 -0600 Subject: [PATCH 01/13] drafting where to work --- docs/contribute/where-to-work.md | 99 ++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 docs/contribute/where-to-work.md diff --git a/docs/contribute/where-to-work.md b/docs/contribute/where-to-work.md new file mode 100644 index 000000000..7b3f4989f --- /dev/null +++ b/docs/contribute/where-to-work.md @@ -0,0 +1,99 @@ + +## **How do I know where to contribute?** + +The easiest way to find the source file for the page you want to update is to navigate to the page on the web and click **Edit this page**. This will take you to the source file in the correct repo. + +The following outlines the general guidelines though to help you determine where the content might be living. + +### **9.0+ content** + +For all 9.0+ content, it lives in one of three spots: + +1. **Reference/settings content** lives in the new Markdown files in the code repo as it did pre 9.0. This enables folks to make updates that touch code \+ low-level docs in the same PR. +2. **Narrative/conceptual and overview content** lives in [elastic/docs-content](https://github.com/elastic/docs-content). As an example the [ES|QL overview](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/explore-analyze/query-filter/languages/esql) lives in the **Explore & Analyze** section of the narrative docs. But the reference documentation lives in the reference section of the docs [ES|QL reference](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/esql) +3. **API reference docs** live in the different OpenAPI spec repositories. This is where you need to update API docs published in the new API docs system + +### **All content prior to 9.0+** + +If you are working in 8.x or below, you will use the existing asciidoc system. This means that if you need to update documentation for both 8.x and 9.x, you will have to work in two systems. See [What if I need to update both 8.x and 9.x docs?](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/contribute/on-the-web#what-if-i-need-to-update-both-8.x-and-9.x-docs) for the processes on updating docs across different versions. + +## Product areas + +### **Kibana** + +#### **What has moved to elastic/docs-content?** + +Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs: + +* explore-analyze: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools... +* deploy-manage: Stack management (Spaces, user management, remote clusters...) +* troubleshooting: troubleshooting pages + +#### **What is staying in the Kibana repo?** + +* Reference content (= anything that is or could be auto-generated): Settings, syntax references, functions lists... +* Release notes +* Developer guide + +### **Elasticsearch** + +#### **What has moved to elastic/docs-content?** + +Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs: + +* explore-analyze: query languages, scripting, machine learning (NLP) +* deploy-manage: deploying elastic, production guidance, security, and Management +* Manage-data: data store, migration, data lifecycle +* solutions: core search, playground, hybrid search +* troubleshooting: troubleshooting pages + +#### **What is staying in the Elasticsearch repo?** + +* Reference content (anything that is or could be auto-generated): Settings, syntax references, functions lists… +* Contribution guides and extending elasticsearch (clients, etc) +* Release notes + +### **Cloud** + +#### **What has moved to elastic/docs-content?** + +Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs: + +* deploy-manage: deploying cloud, managing your cloud organization +* troubleshooting: troubleshooting pages + +#### **What is staying in the Cloud repo?** + +* Reference content (= anything that is or could be auto-generated): Settings, syntax references, functions lists… +* Release notes + +### **Machine learning** + +#### **What has moved to elastic/docs-content?** + +Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs: + +* deploy-manage: deploying cloud, managing your cloud organization +* troubleshooting: troubleshooting pages + +#### **What is staying in the Elasticsearch repo?** + +* Reference content (= anything that is or could be auto-generated): Settings, syntax references, functions lists… +* Release notes + +## **IA Sections to product areas** + +The following section shows a mapping of the different areas in the docs IA to the product areas and topics. + +| **Area** | **Description** | **Sources (Area / Topic)** | +| ----- | ----- | ----- | +| **Get started** | Content in this section focuses on learning about Elasticsearch and the stack, learning about how it can be deployed, and basic environment setup for initial exploration. | | +| **Solutions and use cases** | Content in this section focuses on the core solutions themselves and their user cases. | **Search:** core search solution content, playground, hybrid search **Observability:** core observability content **Security:** core security content | +| **Manage data** | Content in this section focuses on learning about Elastic data store primitives, evaluating and implementing ingestion and data enrichment technologies, managing the lifecycle of your data and migrating data between clusters. | **Elasticsearch:** data store, migration, data lifecycle **Ingest:** ingesting data into Elasticsearch **Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools. | +| **Explore and analyze** | Content in this section focusing on querying, visualizing, and exploring data. Additionally it focusing on levering machine learning for data analysis and defining and responding to alerts | **Elasticsearch:** query languages, scripting, machine learning (NLP) **Machine Learning:** Anomaly detection, data frame analytics, NLP **Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools. **ResponseOps:** Alerts and Cases | +| **Deploy and manage** | Content in this section focuses on evaluating deployment options and setting your environment up. This section also contains content around managing, securing, and monitoring your cluster. | **Elasticsearch:** deploying elastic, production guidance, security, and Management | +| **Manage your Cloud account** | Content in this section focuses specifically on managing Cloud accounts. | | +| **Troubleshoot** | Content in this section is troubleshooting content for the different products as well as how to contact support. | **All troubleshooting content** | +| **Extend and contribute** | Content in this section focuses on contributing to Elastic products and building plugins, clients, and beats modules. | **Contributions guides for:** Kibana Logstash Beats **Developer guides for:** Integrations Elasticsearch Plugins | +| **Reference** | Content in this section focuses on manuals for optional products as well as reference materials like query language references, configuration references, etc. | **Elastic APIS Elastic Clients Query Languages APM Agents Kibana:** Reference content, Release notes, Developer guide | + From 8beb4db03f7f66650635b84efc46129fd1ab670d Mon Sep 17 00:00:00 2001 From: George Wallace Date: Tue, 18 Mar 2025 14:57:25 -0600 Subject: [PATCH 02/13] updates --- docs/contribute/where-to-work.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/contribute/where-to-work.md b/docs/contribute/where-to-work.md index 7b3f4989f..e27761696 100644 --- a/docs/contribute/where-to-work.md +++ b/docs/contribute/where-to-work.md @@ -1,11 +1,11 @@ -## **How do I know where to contribute?** +# **How do I know where to contribute?** The easiest way to find the source file for the page you want to update is to navigate to the page on the web and click **Edit this page**. This will take you to the source file in the correct repo. The following outlines the general guidelines though to help you determine where the content might be living. -### **9.0+ content** +## **9.0+ content** For all 9.0+ content, it lives in one of three spots: @@ -13,7 +13,7 @@ For all 9.0+ content, it lives in one of three spots: 2. **Narrative/conceptual and overview content** lives in [elastic/docs-content](https://github.com/elastic/docs-content). As an example the [ES|QL overview](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/explore-analyze/query-filter/languages/esql) lives in the **Explore & Analyze** section of the narrative docs. But the reference documentation lives in the reference section of the docs [ES|QL reference](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/esql) 3. **API reference docs** live in the different OpenAPI spec repositories. This is where you need to update API docs published in the new API docs system -### **All content prior to 9.0+** +## **All content prior to 9.0+** If you are working in 8.x or below, you will use the existing asciidoc system. This means that if you need to update documentation for both 8.x and 9.x, you will have to work in two systems. See [What if I need to update both 8.x and 9.x docs?](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/contribute/on-the-web#what-if-i-need-to-update-both-8.x-and-9.x-docs) for the processes on updating docs across different versions. From cba4e4835665812f8a07b48ab5992097f2c26d4e Mon Sep 17 00:00:00 2001 From: George Wallace Date: Tue, 18 Mar 2025 14:58:47 -0600 Subject: [PATCH 03/13] fixing typo --- docs/contribute/where-to-work.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribute/where-to-work.md b/docs/contribute/where-to-work.md index e27761696..65ea381e0 100644 --- a/docs/contribute/where-to-work.md +++ b/docs/contribute/where-to-work.md @@ -90,7 +90,7 @@ The following section shows a mapping of the different areas in the docs IA to t | **Get started** | Content in this section focuses on learning about Elasticsearch and the stack, learning about how it can be deployed, and basic environment setup for initial exploration. | | | **Solutions and use cases** | Content in this section focuses on the core solutions themselves and their user cases. | **Search:** core search solution content, playground, hybrid search **Observability:** core observability content **Security:** core security content | | **Manage data** | Content in this section focuses on learning about Elastic data store primitives, evaluating and implementing ingestion and data enrichment technologies, managing the lifecycle of your data and migrating data between clusters. | **Elasticsearch:** data store, migration, data lifecycle **Ingest:** ingesting data into Elasticsearch **Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools. | -| **Explore and analyze** | Content in this section focusing on querying, visualizing, and exploring data. Additionally it focusing on levering machine learning for data analysis and defining and responding to alerts | **Elasticsearch:** query languages, scripting, machine learning (NLP) **Machine Learning:** Anomaly detection, data frame analytics, NLP **Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools. **ResponseOps:** Alerts and Cases | +| **Explore and analyze** | Content in this section focusing on querying, visualizing, and exploring data. Additionally it focusing on leveraging machine learning for data analysis and defining and responding to alerts | **Elasticsearch:** query languages, scripting, machine learning (NLP) **Machine Learning:** Anomaly detection, data frame analytics, NLP **Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools. **ResponseOps:** Alerts and Cases | | **Deploy and manage** | Content in this section focuses on evaluating deployment options and setting your environment up. This section also contains content around managing, securing, and monitoring your cluster. | **Elasticsearch:** deploying elastic, production guidance, security, and Management | | **Manage your Cloud account** | Content in this section focuses specifically on managing Cloud accounts. | | | **Troubleshoot** | Content in this section is troubleshooting content for the different products as well as how to contact support. | **All troubleshooting content** | From 2d9cf90bd390367f34c0627ae226403beb0ab9a5 Mon Sep 17 00:00:00 2001 From: George Wallace Date: Tue, 25 Mar 2025 21:34:46 -0600 Subject: [PATCH 04/13] fixing pages --- docs/contribute/index.md | 96 ++++++++++++++++++++++++++++++- docs/contribute/where-to-work.md | 99 -------------------------------- 2 files changed, 94 insertions(+), 101 deletions(-) delete mode 100644 docs/contribute/where-to-work.md diff --git a/docs/contribute/index.md b/docs/contribute/index.md index 0af35e1c1..12157bb6e 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -10,17 +10,27 @@ Whether you're a technical writer or you've only edited Elastic docs once or twi ## Contribute to the docs [#contribute] -The version of the docs you want to contribute to determines the tool and syntax you must use to update the docs. +The version of the docs you want to contribute to determines the tool and syntax you must use to update the docs. The easiest way to find the source file for the page you want to update is to navigate to the page on the web and click **Edit this page**. This will take you to the source file in the correct repo. ### Contribute to Elastic Stack version 8.x docs and earlier -To contribute to earlier versions of the Elastic Stack, you must work with our [legacy documentation build system](https://github.com/elastic/docs). This system uses AsciiDoc as it's authoring format. +To contribute to earlier versions of the Elastic Stack, you must work with our [legacy documentation build system](https://github.com/elastic/docs). This system uses AsciiDoc as it's authoring format. * For **simple bugfixes and enhancements** --> [Contribute on the web](on-the-web.md) * For **complex or multi-page updates** --> See the [legacy documentation build guide](https://github.com/elastic/docs?tab=readme-ov-file#building-documentation) +If you need to update documentation for both 8.x and 9.x, you will have to work in two systems. See [What if I need to update both 8.x and 9.x docs?](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/contribute/on-the-web#what-if-i-need-to-update-both-8.x-and-9.x-docs) for the processes on updating docs across different versions. + ### Contribute to Elastic Stack version 9.0 docs and later +For all 9.0+ content, it lives in one of three spots: + +1. **Reference/settings content** lives in the new Markdown files in the code repo as it did pre 9.0. This enables folks to make updates that touch code \+ low-level docs in the same PR. +2. **Narrative/conceptual and overview content** lives in [elastic/docs-content](https://github.com/elastic/docs-content). As an example the [ES|QL overview](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/explore-analyze/query-filter/languages/esql) lives in the **Explore & Analyze** section of the narrative docs. But the reference documentation lives in the reference section of the docs [ES|QL reference](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/esql) +3. **API reference docs** live in the different OpenAPI spec repositories. This is where you need to update API docs published in the new API docs system + +When you are ready to edit the content: + * For **simple bugfixes and enhancements** --> [contribute on the web](on-the-web.md) * For **complex or multi-page updates** --> [Contribute locally](locally.md) @@ -37,3 +47,85 @@ To contribute to earlier versions of the Elastic Stack, you must work with our [ ## Work on docs-builder That sounds great! See [development](../development/index.md) to learn how to contribute to our documentation build system. + +## Where does the content live + +You can use the following sections to help you determine where the content you might want to work on lives. + +### Kibana + +#### What has moved to elastic/docs-content? + +Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs: + +* explore-analyze: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools... +* deploy-manage: Stack management (Spaces, user management, remote clusters...) +* troubleshooting: troubleshooting pages + +#### What is staying in the Kibana repo? + +* Reference content (= anything that is or could be auto-generated): Settings, syntax references, functions lists... +* Release notes +* Developer guide + +### Elasticsearch + +#### What has moved to elastic/docs-content? + +Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs: + +* explore-analyze: query languages, scripting, machine learning (NLP) +* deploy-manage: deploying elastic, production guidance, security, and Management +* Manage-data: data store, migration, data lifecycle +* solutions: core search, playground, hybrid search +* troubleshooting: troubleshooting pages + +#### What is staying in the Elasticsearch repo? + +* Reference content (anything that is or could be auto-generated): Settings, syntax references, functions lists… +* Contribution guides and extending elasticsearch (clients, etc) +* Release notes + +### Cloud + +#### What has moved to elastic/docs-content? + +Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs: + +* deploy-manage: deploying cloud, managing your cloud organization +* troubleshooting: troubleshooting pages + +#### **What is staying in the Cloud repo?** + +* Reference content (= anything that is or could be auto-generated): Settings, syntax references, functions lists… +* Release notes + +### Machine learning + +#### What has moved to elastic/docs-content? + +Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs: + +* deploy-manage: deploying cloud, managing your cloud organization +* troubleshooting: troubleshooting pages + +#### What is staying in the Elasticsearch repo? + +* Reference content (= anything that is or could be auto-generated): Settings, syntax references, functions lists… +* Release notes + +## IA Sections to product areas + +The following section shows a mapping of the different areas in the docs IA to the product areas and topics. + +| **Area** | **Description** | **Sources (Area / Topic)** | +| ----- | ----- | ----- | +| **Get started** | Content in this section focuses on learning about Elasticsearch and the stack, learning about how it can be deployed, and basic environment setup for initial exploration. | | +| **Solutions and use cases** | Content in this section focuses on the core solutions themselves and their user cases. | **Search:** core search solution content, playground, hybrid search **Observability:** core observability content **Security:** core security content | +| **Manage data** | Content in this section focuses on learning about Elastic data store primitives, evaluating and implementing ingestion and data enrichment technologies, managing the lifecycle of your data and migrating data between clusters. | **Elasticsearch:** data store, migration, data lifecycle **Ingest:** ingesting data into Elasticsearch **Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools. | +| **Explore and analyze** | Content in this section focusing on querying, visualizing, and exploring data. Additionally it focusing on leveraging machine learning for data analysis and defining and responding to alerts | **Elasticsearch:** query languages, scripting, machine learning (NLP) **Machine Learning:** Anomaly detection, data frame analytics, NLP **Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools. **ResponseOps:** Alerts and Cases | +| **Deploy and manage** | Content in this section focuses on evaluating deployment options and setting your environment up. This section also contains content around managing, securing, and monitoring your cluster. | **Elasticsearch:** deploying elastic, production guidance, security, and Management | +| **Manage your Cloud account** | Content in this section focuses specifically on managing Cloud accounts. | | +| **Troubleshoot** | Content in this section is troubleshooting content for the different products as well as how to contact support. | **All troubleshooting content** | +| **Extend and contribute** | Content in this section focuses on contributing to Elastic products and building plugins, clients, and beats modules. | **Contributions guides for:** Kibana Logstash Beats **Developer guides for:** Integrations Elasticsearch Plugins | +| **Reference** | Content in this section focuses on manuals for optional products as well as reference materials like query language references, configuration references, etc. | **Elastic APIS Elastic Clients Query Languages APM Agents Kibana:** Reference content, Release notes, Developer guide | diff --git a/docs/contribute/where-to-work.md b/docs/contribute/where-to-work.md deleted file mode 100644 index 65ea381e0..000000000 --- a/docs/contribute/where-to-work.md +++ /dev/null @@ -1,99 +0,0 @@ - -# **How do I know where to contribute?** - -The easiest way to find the source file for the page you want to update is to navigate to the page on the web and click **Edit this page**. This will take you to the source file in the correct repo. - -The following outlines the general guidelines though to help you determine where the content might be living. - -## **9.0+ content** - -For all 9.0+ content, it lives in one of three spots: - -1. **Reference/settings content** lives in the new Markdown files in the code repo as it did pre 9.0. This enables folks to make updates that touch code \+ low-level docs in the same PR. -2. **Narrative/conceptual and overview content** lives in [elastic/docs-content](https://github.com/elastic/docs-content). As an example the [ES|QL overview](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/explore-analyze/query-filter/languages/esql) lives in the **Explore & Analyze** section of the narrative docs. But the reference documentation lives in the reference section of the docs [ES|QL reference](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/esql) -3. **API reference docs** live in the different OpenAPI spec repositories. This is where you need to update API docs published in the new API docs system - -## **All content prior to 9.0+** - -If you are working in 8.x or below, you will use the existing asciidoc system. This means that if you need to update documentation for both 8.x and 9.x, you will have to work in two systems. See [What if I need to update both 8.x and 9.x docs?](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/contribute/on-the-web#what-if-i-need-to-update-both-8.x-and-9.x-docs) for the processes on updating docs across different versions. - -## Product areas - -### **Kibana** - -#### **What has moved to elastic/docs-content?** - -Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs: - -* explore-analyze: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools... -* deploy-manage: Stack management (Spaces, user management, remote clusters...) -* troubleshooting: troubleshooting pages - -#### **What is staying in the Kibana repo?** - -* Reference content (= anything that is or could be auto-generated): Settings, syntax references, functions lists... -* Release notes -* Developer guide - -### **Elasticsearch** - -#### **What has moved to elastic/docs-content?** - -Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs: - -* explore-analyze: query languages, scripting, machine learning (NLP) -* deploy-manage: deploying elastic, production guidance, security, and Management -* Manage-data: data store, migration, data lifecycle -* solutions: core search, playground, hybrid search -* troubleshooting: troubleshooting pages - -#### **What is staying in the Elasticsearch repo?** - -* Reference content (anything that is or could be auto-generated): Settings, syntax references, functions lists… -* Contribution guides and extending elasticsearch (clients, etc) -* Release notes - -### **Cloud** - -#### **What has moved to elastic/docs-content?** - -Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs: - -* deploy-manage: deploying cloud, managing your cloud organization -* troubleshooting: troubleshooting pages - -#### **What is staying in the Cloud repo?** - -* Reference content (= anything that is or could be auto-generated): Settings, syntax references, functions lists… -* Release notes - -### **Machine learning** - -#### **What has moved to elastic/docs-content?** - -Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs: - -* deploy-manage: deploying cloud, managing your cloud organization -* troubleshooting: troubleshooting pages - -#### **What is staying in the Elasticsearch repo?** - -* Reference content (= anything that is or could be auto-generated): Settings, syntax references, functions lists… -* Release notes - -## **IA Sections to product areas** - -The following section shows a mapping of the different areas in the docs IA to the product areas and topics. - -| **Area** | **Description** | **Sources (Area / Topic)** | -| ----- | ----- | ----- | -| **Get started** | Content in this section focuses on learning about Elasticsearch and the stack, learning about how it can be deployed, and basic environment setup for initial exploration. | | -| **Solutions and use cases** | Content in this section focuses on the core solutions themselves and their user cases. | **Search:** core search solution content, playground, hybrid search **Observability:** core observability content **Security:** core security content | -| **Manage data** | Content in this section focuses on learning about Elastic data store primitives, evaluating and implementing ingestion and data enrichment technologies, managing the lifecycle of your data and migrating data between clusters. | **Elasticsearch:** data store, migration, data lifecycle **Ingest:** ingesting data into Elasticsearch **Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools. | -| **Explore and analyze** | Content in this section focusing on querying, visualizing, and exploring data. Additionally it focusing on leveraging machine learning for data analysis and defining and responding to alerts | **Elasticsearch:** query languages, scripting, machine learning (NLP) **Machine Learning:** Anomaly detection, data frame analytics, NLP **Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools. **ResponseOps:** Alerts and Cases | -| **Deploy and manage** | Content in this section focuses on evaluating deployment options and setting your environment up. This section also contains content around managing, securing, and monitoring your cluster. | **Elasticsearch:** deploying elastic, production guidance, security, and Management | -| **Manage your Cloud account** | Content in this section focuses specifically on managing Cloud accounts. | | -| **Troubleshoot** | Content in this section is troubleshooting content for the different products as well as how to contact support. | **All troubleshooting content** | -| **Extend and contribute** | Content in this section focuses on contributing to Elastic products and building plugins, clients, and beats modules. | **Contributions guides for:** Kibana Logstash Beats **Developer guides for:** Integrations Elasticsearch Plugins | -| **Reference** | Content in this section focuses on manuals for optional products as well as reference materials like query language references, configuration references, etc. | **Elastic APIS Elastic Clients Query Languages APM Agents Kibana:** Reference content, Release notes, Developer guide | - From 1e2a0712a0e3412f9916461209346eef3cc76516 Mon Sep 17 00:00:00 2001 From: George Wallace Date: Fri, 28 Mar 2025 11:06:58 -0600 Subject: [PATCH 05/13] fixing up content, adding missing sections --- docs/contribute/index.md | 47 ++++++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 23 deletions(-) diff --git a/docs/contribute/index.md b/docs/contribute/index.md index 12157bb6e..ad84cb4ef 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -58,13 +58,13 @@ You can use the following sections to help you determine where the content you m Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs: -* explore-analyze: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools... -* deploy-manage: Stack management (Spaces, user management, remote clusters...) -* troubleshooting: troubleshooting pages +* **explore-analyze**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools... +* **deploy-manage**: Stack management (Spaces, user management, remote clusters...) +* **troubleshooting**: troubleshooting pages #### What is staying in the Kibana repo? -* Reference content (= anything that is or could be auto-generated): Settings, syntax references, functions lists... +* Reference content, anything that is or could be auto-generated: Settings, syntax references, functions lists... * Release notes * Developer guide @@ -74,11 +74,11 @@ Public-facing narrative and conceptual docs have moved. Most can now be found un Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs: -* explore-analyze: query languages, scripting, machine learning (NLP) -* deploy-manage: deploying elastic, production guidance, security, and Management -* Manage-data: data store, migration, data lifecycle -* solutions: core search, playground, hybrid search -* troubleshooting: troubleshooting pages +* **explore-analyze**: query languages, scripting, machine learning (NLP) +* **deploy-manage**: deploying elastic, production guidance, security, and Management +* **manage-data**: data store, migration, data lifecycle +* **solutions**: core search, playground, hybrid search +* **troubleshooting**: troubleshooting pages #### What is staying in the Elasticsearch repo? @@ -92,8 +92,9 @@ Public-facing narrative and conceptual docs have moved. Most can now be found un Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs: -* deploy-manage: deploying cloud, managing your cloud organization -* troubleshooting: troubleshooting pages +* **deploy-manage**: deploying cloud +* **cloud-account**: managing your cloud organization +* **troubleshooting**: troubleshooting pages #### **What is staying in the Cloud repo?** @@ -106,12 +107,12 @@ Public-facing narrative and conceptual docs have moved. Most can now be found un Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs: -* deploy-manage: deploying cloud, managing your cloud organization -* troubleshooting: troubleshooting pages +* **deploy-manage**: deploying cloud, managing your cloud organization +* **troubleshooting**: troubleshooting pages #### What is staying in the Elasticsearch repo? -* Reference content (= anything that is or could be auto-generated): Settings, syntax references, functions lists… +* Reference content, anything that is or could be auto-generated): Settings, syntax references, functions lists… * Release notes ## IA Sections to product areas @@ -120,12 +121,12 @@ The following section shows a mapping of the different areas in the docs IA to t | **Area** | **Description** | **Sources (Area / Topic)** | | ----- | ----- | ----- | -| **Get started** | Content in this section focuses on learning about Elasticsearch and the stack, learning about how it can be deployed, and basic environment setup for initial exploration. | | -| **Solutions and use cases** | Content in this section focuses on the core solutions themselves and their user cases. | **Search:** core search solution content, playground, hybrid search **Observability:** core observability content **Security:** core security content | -| **Manage data** | Content in this section focuses on learning about Elastic data store primitives, evaluating and implementing ingestion and data enrichment technologies, managing the lifecycle of your data and migrating data between clusters. | **Elasticsearch:** data store, migration, data lifecycle **Ingest:** ingesting data into Elasticsearch **Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools. | -| **Explore and analyze** | Content in this section focusing on querying, visualizing, and exploring data. Additionally it focusing on leveraging machine learning for data analysis and defining and responding to alerts | **Elasticsearch:** query languages, scripting, machine learning (NLP) **Machine Learning:** Anomaly detection, data frame analytics, NLP **Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools. **ResponseOps:** Alerts and Cases | -| **Deploy and manage** | Content in this section focuses on evaluating deployment options and setting your environment up. This section also contains content around managing, securing, and monitoring your cluster. | **Elasticsearch:** deploying elastic, production guidance, security, and Management | -| **Manage your Cloud account** | Content in this section focuses specifically on managing Cloud accounts. | | -| **Troubleshoot** | Content in this section is troubleshooting content for the different products as well as how to contact support. | **All troubleshooting content** | -| **Extend and contribute** | Content in this section focuses on contributing to Elastic products and building plugins, clients, and beats modules. | **Contributions guides for:** Kibana Logstash Beats **Developer guides for:** Integrations Elasticsearch Plugins | -| **Reference** | Content in this section focuses on manuals for optional products as well as reference materials like query language references, configuration references, etc. | **Elastic APIS Elastic Clients Query Languages APM Agents Kibana:** Reference content, Release notes, Developer guide | +| **Get started** | Content in this section focuses on learning about Elasticsearch and the stack, learning about how it can be deployed, and basic environment setup for initial exploration. | Overview of Elastic and various topics | +| **Solutions and use cases** | Content in this section focuses on the core solutions themselves and their user cases. | **Search:** core search solution content, playground, hybrid search
**Observability:** core observability content
**Security:** core security content | +| **Manage data** | Content in this section focuses on learning about Elastic data store primitives, evaluating and implementing ingestion and data enrichment technologies, managing the lifecycle of your data and migrating data between clusters. | **Elasticsearch:** data store, migration, data lifecycle
**Ingest:** ingesting data into Elasticsearch
**Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools. | +| **Explore and analyze** | Content in this section focusing on querying, visualizing, and exploring data. Additionally it focusing on leveraging machine learning for data analysis and defining and responding to alerts | **Elasticsearch:** query languages, scripting, machine learning (NLP)
**Machine Learning:** Anomaly detection, data frame analytics, NLP
**Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools.
**ResponseOps:** Alerts and Cases | +| **Deploy and manage** | Content in this section focuses on evaluating deployment options and setting your environment up. This section also contains content around managing, securing, and monitoring your cluster. | **Elasticsearch:** deploying elastic, production guidance, security, and Management
**Cloud:** deploying and managing Elastic Cloud, Elastic Cloud Enterprise, Serverless, and ECK. | +| **Manage your Cloud account** | Content in this section focuses specifically on managing Cloud accounts. | **Cloud:** Managing your cloud account | +| **Troubleshoot** | Content in this section is troubleshooting content for the different products as well as how to contact support. | All troubleshooting content | +| **Extend and contribute** | Content in this section focuses on contributing to Elastic products and building plugins, clients, and beats modules. | **Contributions guides for:** Kibana Logstash Beats
**Developer guides for:** Integrations Elasticsearch Plugins | +| **Reference** | Content in this section focuses on manuals for optional products as well as reference materials like query language references, configuration references, etc. | Reference content, Release notes, Developer guide | From 9f925667a108dbe47d83efbbabc44ba912be0a22 Mon Sep 17 00:00:00 2001 From: George Wallace Date: Wed, 2 Apr 2025 07:47:09 -0600 Subject: [PATCH 06/13] Apply suggestions from code review Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com> --- docs/contribute/index.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/contribute/index.md b/docs/contribute/index.md index ad84cb4ef..b332a6d5b 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -12,22 +12,23 @@ Whether you're a technical writer or you've only edited Elastic docs once or twi The version of the docs you want to contribute to determines the tool and syntax you must use to update the docs. The easiest way to find the source file for the page you want to update is to navigate to the page on the web and click **Edit this page**. This will take you to the source file in the correct repo. -### Contribute to Elastic Stack version 8.x docs and earlier +### Contribute to version `8.x` docs and earlier -To contribute to earlier versions of the Elastic Stack, you must work with our [legacy documentation build system](https://github.com/elastic/docs). This system uses AsciiDoc as it's authoring format. +To contribute to earlier versions of the Elastic Stack, you must work with our [legacy documentation build system](https://github.com/elastic/docs). This system uses the [AsciiDoc](https://asciidoc.org) markup language. * For **simple bugfixes and enhancements** --> [Contribute on the web](on-the-web.md) * For **complex or multi-page updates** --> See the [legacy documentation build guide](https://github.com/elastic/docs?tab=readme-ov-file#building-documentation) If you need to update documentation for both 8.x and 9.x, you will have to work in two systems. See [What if I need to update both 8.x and 9.x docs?](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/contribute/on-the-web#what-if-i-need-to-update-both-8.x-and-9.x-docs) for the processes on updating docs across different versions. -### Contribute to Elastic Stack version 9.0 docs and later +### Contribute to version `9.0` docs and later -For all 9.0+ content, it lives in one of three spots: +To contribute to `9.0+` content, you need to work with our new documentation system. This system uses custom [Markdown syntax](syntax.md). +This content lives in one of three places: -1. **Reference/settings content** lives in the new Markdown files in the code repo as it did pre 9.0. This enables folks to make updates that touch code \+ low-level docs in the same PR. -2. **Narrative/conceptual and overview content** lives in [elastic/docs-content](https://github.com/elastic/docs-content). As an example the [ES|QL overview](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/explore-analyze/query-filter/languages/esql) lives in the **Explore & Analyze** section of the narrative docs. But the reference documentation lives in the reference section of the docs [ES|QL reference](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/esql) -3. **API reference docs** live in the different OpenAPI spec repositories. This is where you need to update API docs published in the new API docs system +1. **Reference/settings content** lives in the new Markdown files in the code repo as it did pre 9.0. This enables folks to make updates that touch code and low-level docs in the same PR. +2. **Narrative/conceptual and overview content** lives in [elastic/docs-content](https://github.com/elastic/docs-content). For example, the [ES|QL overview](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/explore-analyze/query-filter/languages/esql) lives in the **Explore & Analyze** section of the narrative docs. But the reference documentation lives in the Elasticsearch reference section of the docs: [ES|QL reference](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/esql) +3. **API reference docs** live in the different OpenAPI spec repositories. This is where you need to update API docs published in the new API docs system. When you are ready to edit the content: @@ -50,7 +51,7 @@ That sounds great! See [development](../development/index.md) to learn how to co ## Where does the content live -You can use the following sections to help you determine where the content you might want to work on lives. +Understand where your content of interest now sits in the new docs information architecture and the repos where source pages live. ### Kibana @@ -115,7 +116,7 @@ Public-facing narrative and conceptual docs have moved. Most can now be found un * Reference content, anything that is or could be auto-generated): Settings, syntax references, functions lists… * Release notes -## IA Sections to product areas +## How is content organized across documentation sections? The following section shows a mapping of the different areas in the docs IA to the product areas and topics. @@ -124,7 +125,7 @@ The following section shows a mapping of the different areas in the docs IA to t | **Get started** | Content in this section focuses on learning about Elasticsearch and the stack, learning about how it can be deployed, and basic environment setup for initial exploration. | Overview of Elastic and various topics | | **Solutions and use cases** | Content in this section focuses on the core solutions themselves and their user cases. | **Search:** core search solution content, playground, hybrid search
**Observability:** core observability content
**Security:** core security content | | **Manage data** | Content in this section focuses on learning about Elastic data store primitives, evaluating and implementing ingestion and data enrichment technologies, managing the lifecycle of your data and migrating data between clusters. | **Elasticsearch:** data store, migration, data lifecycle
**Ingest:** ingesting data into Elasticsearch
**Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools. | -| **Explore and analyze** | Content in this section focusing on querying, visualizing, and exploring data. Additionally it focusing on leveraging machine learning for data analysis and defining and responding to alerts | **Elasticsearch:** query languages, scripting, machine learning (NLP)
**Machine Learning:** Anomaly detection, data frame analytics, NLP
**Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools.
**ResponseOps:** Alerts and Cases | +| **Explore and analyze** | Content in this section focuses on querying, visualizing, and exploring data. Additionally it focusing on leveraging machine learning for data analysis and defining and responding to alerts | **Elasticsearch:** query languages, scripting, machine learning (NLP)
**Machine Learning:** Anomaly detection, data frame analytics, NLP
**Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools.
**ResponseOps:** Alerts and Cases | | **Deploy and manage** | Content in this section focuses on evaluating deployment options and setting your environment up. This section also contains content around managing, securing, and monitoring your cluster. | **Elasticsearch:** deploying elastic, production guidance, security, and Management
**Cloud:** deploying and managing Elastic Cloud, Elastic Cloud Enterprise, Serverless, and ECK. | | **Manage your Cloud account** | Content in this section focuses specifically on managing Cloud accounts. | **Cloud:** Managing your cloud account | | **Troubleshoot** | Content in this section is troubleshooting content for the different products as well as how to contact support. | All troubleshooting content | From c0fc85c9261ccf18210704a7b2727e962da91c4b Mon Sep 17 00:00:00 2001 From: George Wallace Date: Wed, 2 Apr 2025 07:51:05 -0600 Subject: [PATCH 07/13] reordering page --- docs/contribute/index.md | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/docs/contribute/index.md b/docs/contribute/index.md index b332a6d5b..ef871a0a1 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -10,7 +10,7 @@ Whether you're a technical writer or you've only edited Elastic docs once or twi ## Contribute to the docs [#contribute] -The version of the docs you want to contribute to determines the tool and syntax you must use to update the docs. The easiest way to find the source file for the page you want to update is to navigate to the page on the web and click **Edit this page**. This will take you to the source file in the correct repo. +The version of the docs you want to contribute to determines the tool and syntax you must use to update the docs. The easiest way to find the source file for the page you want to update is to navigate to the page on the web and click **Edit this page**. This will take you to the source file in the correct repo. For more detailed instructions, see [Contribute on the web](on-the-web.md). ### Contribute to version `8.x` docs and earlier @@ -35,20 +35,6 @@ When you are ready to edit the content: * For **simple bugfixes and enhancements** --> [contribute on the web](on-the-web.md) * For **complex or multi-page updates** --> [Contribute locally](locally.md) -## Report a bug - -* It's a **documentation** problem --> [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml) *or* [Fix it myself](locally.md) -* It's a **build tool (docs-builder)** problem --> [Open a bug report](https://github.com/elastic/docs-builder/issues/new?template=bug-report.yaml) - -## Request an enhancement - -* Make the **documentation** better --> [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml) -* Make our **build tool (docs-builder)** better --> [Start a docs-builder discussion](https://github.com/elastic/docs-builder/discussions) - -## Work on docs-builder - -That sounds great! See [development](../development/index.md) to learn how to contribute to our documentation build system. - ## Where does the content live Understand where your content of interest now sits in the new docs information architecture and the repos where source pages live. @@ -131,3 +117,18 @@ The following section shows a mapping of the different areas in the docs IA to t | **Troubleshoot** | Content in this section is troubleshooting content for the different products as well as how to contact support. | All troubleshooting content | | **Extend and contribute** | Content in this section focuses on contributing to Elastic products and building plugins, clients, and beats modules. | **Contributions guides for:** Kibana Logstash Beats
**Developer guides for:** Integrations Elasticsearch Plugins | | **Reference** | Content in this section focuses on manuals for optional products as well as reference materials like query language references, configuration references, etc. | Reference content, Release notes, Developer guide | + +## Report a bug + +* It's a **documentation** problem --> [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml) *or* [Fix it myself](locally.md) +* It's a **build tool (docs-builder)** problem --> [Open a bug report](https://github.com/elastic/docs-builder/issues/new?template=bug-report.yaml) + +## Request an enhancement + +* Make the **documentation** better --> [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml) +* Make our **build tool (docs-builder)** better --> [Start a docs-builder discussion](https://github.com/elastic/docs-builder/discussions) + +## Work on docs-builder + +That sounds great! See [development](../development/index.md) to learn how to contribute to our documentation build system. + From be112b5c7de5443257a15b16cfa42197fd87f0a1 Mon Sep 17 00:00:00 2001 From: George Wallace Date: Wed, 2 Apr 2025 07:59:25 -0600 Subject: [PATCH 08/13] fixing build error --- docs/contribute/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribute/index.md b/docs/contribute/index.md index ef871a0a1..c38d8ae25 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -23,7 +23,7 @@ If you need to update documentation for both 8.x and 9.x, you will have to work ### Contribute to version `9.0` docs and later -To contribute to `9.0+` content, you need to work with our new documentation system. This system uses custom [Markdown syntax](syntax.md). +To contribute to `9.0+` content, you need to work with our new documentation system. This system uses custom [Markdown syntax](../syntax/index.md). This content lives in one of three places: 1. **Reference/settings content** lives in the new Markdown files in the code repo as it did pre 9.0. This enables folks to make updates that touch code and low-level docs in the same PR. From a42c41f77d5c5c1a054b46c0868ded3a999844db Mon Sep 17 00:00:00 2001 From: George Wallace Date: Wed, 2 Apr 2025 08:08:55 -0600 Subject: [PATCH 09/13] correcting line breaks --- docs/contribute/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/contribute/index.md b/docs/contribute/index.md index c38d8ae25..ab83c4965 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -109,13 +109,13 @@ The following section shows a mapping of the different areas in the docs IA to t | **Area** | **Description** | **Sources (Area / Topic)** | | ----- | ----- | ----- | | **Get started** | Content in this section focuses on learning about Elasticsearch and the stack, learning about how it can be deployed, and basic environment setup for initial exploration. | Overview of Elastic and various topics | -| **Solutions and use cases** | Content in this section focuses on the core solutions themselves and their user cases. | **Search:** core search solution content, playground, hybrid search
**Observability:** core observability content
**Security:** core security content | -| **Manage data** | Content in this section focuses on learning about Elastic data store primitives, evaluating and implementing ingestion and data enrichment technologies, managing the lifecycle of your data and migrating data between clusters. | **Elasticsearch:** data store, migration, data lifecycle
**Ingest:** ingesting data into Elasticsearch
**Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools. | -| **Explore and analyze** | Content in this section focuses on querying, visualizing, and exploring data. Additionally it focusing on leveraging machine learning for data analysis and defining and responding to alerts | **Elasticsearch:** query languages, scripting, machine learning (NLP)
**Machine Learning:** Anomaly detection, data frame analytics, NLP
**Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools.
**ResponseOps:** Alerts and Cases | -| **Deploy and manage** | Content in this section focuses on evaluating deployment options and setting your environment up. This section also contains content around managing, securing, and monitoring your cluster. | **Elasticsearch:** deploying elastic, production guidance, security, and Management
**Cloud:** deploying and managing Elastic Cloud, Elastic Cloud Enterprise, Serverless, and ECK. | +| **Solutions and use cases** | Content in this section focuses on the core solutions themselves and their user cases. | **Search:** core search solution content, playground, hybrid search
**Observability:** core observability content
**Security:** core security content | +| **Manage data** | Content in this section focuses on learning about Elastic data store primitives, evaluating and implementing ingestion and data enrichment technologies, managing the lifecycle of your data and migrating data between clusters. | **Elasticsearch:** data store, migration, data lifecycle
**Ingest:** ingesting data into Elasticsearch
**Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools. | +| **Explore and analyze** | Content in this section focuses on querying, visualizing, and exploring data. Additionally it focusing on leveraging machine learning for data analysis and defining and responding to alerts | **Elasticsearch:** query languages, scripting, machine learning (NLP)
**Machine Learning:** Anomaly detection, data frame analytics, NLP
**Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools.
**ResponseOps:** Alerts and Cases | +| **Deploy and manage** | Content in this section focuses on evaluating deployment options and setting your environment up. This section also contains content around managing, securing, and monitoring your cluster. | **Elasticsearch:** deploying elastic, production guidance, security, and Management
**Cloud:** deploying and managing Elastic Cloud, Elastic Cloud Enterprise, Serverless, and ECK. | | **Manage your Cloud account** | Content in this section focuses specifically on managing Cloud accounts. | **Cloud:** Managing your cloud account | | **Troubleshoot** | Content in this section is troubleshooting content for the different products as well as how to contact support. | All troubleshooting content | -| **Extend and contribute** | Content in this section focuses on contributing to Elastic products and building plugins, clients, and beats modules. | **Contributions guides for:** Kibana Logstash Beats
**Developer guides for:** Integrations Elasticsearch Plugins | +| **Extend and contribute** | Content in this section focuses on contributing to Elastic products and building plugins, clients, and beats modules. | **Contributions guides for:** Kibana Logstash Beats
**Developer guides for:** Integrations Elasticsearch Plugins | | **Reference** | Content in this section focuses on manuals for optional products as well as reference materials like query language references, configuration references, etc. | Reference content, Release notes, Developer guide | ## Report a bug From bc6e69fd1f552623bd9a3ee51d7b6d75104f83a7 Mon Sep 17 00:00:00 2001 From: George Wallace Date: Fri, 4 Apr 2025 10:43:08 -0600 Subject: [PATCH 10/13] Apply suggestions from code review Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com> --- docs/contribute/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contribute/index.md b/docs/contribute/index.md index ab83c4965..5470ccccf 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -35,7 +35,7 @@ When you are ready to edit the content: * For **simple bugfixes and enhancements** --> [contribute on the web](on-the-web.md) * For **complex or multi-page updates** --> [Contribute locally](locally.md) -## Where does the content live +## Where to find docs source files Understand where your content of interest now sits in the new docs information architecture and the repos where source pages live. @@ -102,7 +102,7 @@ Public-facing narrative and conceptual docs have moved. Most can now be found un * Reference content, anything that is or could be auto-generated): Settings, syntax references, functions lists… * Release notes -## How is content organized across documentation sections? +## How docs sections are organized The following section shows a mapping of the different areas in the docs IA to the product areas and topics. From 68f03a5fdf564736b0f801cc0ff92d7aae0b9a5c Mon Sep 17 00:00:00 2001 From: George Wallace Date: Fri, 18 Apr 2025 15:30:44 -0600 Subject: [PATCH 11/13] Update contribution guidelines for documentation versions --- docs/contribute/index.md | 91 ++-------------------------------------- 1 file changed, 4 insertions(+), 87 deletions(-) diff --git a/docs/contribute/index.md b/docs/contribute/index.md index 5470ccccf..f10bfac17 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -12,18 +12,18 @@ Whether you're a technical writer or you've only edited Elastic docs once or twi The version of the docs you want to contribute to determines the tool and syntax you must use to update the docs. The easiest way to find the source file for the page you want to update is to navigate to the page on the web and click **Edit this page**. This will take you to the source file in the correct repo. For more detailed instructions, see [Contribute on the web](on-the-web.md). -### Contribute to version `8.x` docs and earlier +### Contribute to version `8.18`, `ECE 3.8`, and `ECK 2.0` docs and earlier -To contribute to earlier versions of the Elastic Stack, you must work with our [legacy documentation build system](https://github.com/elastic/docs). This system uses the [AsciiDoc](https://asciidoc.org) markup language. +To contribute to earlier versions of the documentation, you must work with our [legacy documentation build system](https://github.com/elastic/docs). This system uses the [AsciiDoc](https://asciidoc.org) markup language. * For **simple bugfixes and enhancements** --> [Contribute on the web](on-the-web.md) * For **complex or multi-page updates** --> See the [legacy documentation build guide](https://github.com/elastic/docs?tab=readme-ov-file#building-documentation) If you need to update documentation for both 8.x and 9.x, you will have to work in two systems. See [What if I need to update both 8.x and 9.x docs?](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/contribute/on-the-web#what-if-i-need-to-update-both-8.x-and-9.x-docs) for the processes on updating docs across different versions. -### Contribute to version `9.0` docs and later +### Contribute to version `9.0+`, `ECE 4.0+`, and `ECK 3.0+` docs and later -To contribute to `9.0+` content, you need to work with our new documentation system. This system uses custom [Markdown syntax](../syntax/index.md). +To contribute to `9.0+`, `ECE 4.0+`, and `ECK 3.0+` content, you need to work with our new documentation system. This system uses custom [Markdown syntax](../syntax/index.md). This content lives in one of three places: 1. **Reference/settings content** lives in the new Markdown files in the code repo as it did pre 9.0. This enables folks to make updates that touch code and low-level docs in the same PR. @@ -35,89 +35,6 @@ When you are ready to edit the content: * For **simple bugfixes and enhancements** --> [contribute on the web](on-the-web.md) * For **complex or multi-page updates** --> [Contribute locally](locally.md) -## Where to find docs source files - -Understand where your content of interest now sits in the new docs information architecture and the repos where source pages live. - -### Kibana - -#### What has moved to elastic/docs-content? - -Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs: - -* **explore-analyze**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools... -* **deploy-manage**: Stack management (Spaces, user management, remote clusters...) -* **troubleshooting**: troubleshooting pages - -#### What is staying in the Kibana repo? - -* Reference content, anything that is or could be auto-generated: Settings, syntax references, functions lists... -* Release notes -* Developer guide - -### Elasticsearch - -#### What has moved to elastic/docs-content? - -Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs: - -* **explore-analyze**: query languages, scripting, machine learning (NLP) -* **deploy-manage**: deploying elastic, production guidance, security, and Management -* **manage-data**: data store, migration, data lifecycle -* **solutions**: core search, playground, hybrid search -* **troubleshooting**: troubleshooting pages - -#### What is staying in the Elasticsearch repo? - -* Reference content (anything that is or could be auto-generated): Settings, syntax references, functions lists… -* Contribution guides and extending elasticsearch (clients, etc) -* Release notes - -### Cloud - -#### What has moved to elastic/docs-content? - -Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs: - -* **deploy-manage**: deploying cloud -* **cloud-account**: managing your cloud organization -* **troubleshooting**: troubleshooting pages - -#### **What is staying in the Cloud repo?** - -* Reference content (= anything that is or could be auto-generated): Settings, syntax references, functions lists… -* Release notes - -### Machine learning - -#### What has moved to elastic/docs-content? - -Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs: - -* **deploy-manage**: deploying cloud, managing your cloud organization -* **troubleshooting**: troubleshooting pages - -#### What is staying in the Elasticsearch repo? - -* Reference content, anything that is or could be auto-generated): Settings, syntax references, functions lists… -* Release notes - -## How docs sections are organized - -The following section shows a mapping of the different areas in the docs IA to the product areas and topics. - -| **Area** | **Description** | **Sources (Area / Topic)** | -| ----- | ----- | ----- | -| **Get started** | Content in this section focuses on learning about Elasticsearch and the stack, learning about how it can be deployed, and basic environment setup for initial exploration. | Overview of Elastic and various topics | -| **Solutions and use cases** | Content in this section focuses on the core solutions themselves and their user cases. | **Search:** core search solution content, playground, hybrid search
**Observability:** core observability content
**Security:** core security content | -| **Manage data** | Content in this section focuses on learning about Elastic data store primitives, evaluating and implementing ingestion and data enrichment technologies, managing the lifecycle of your data and migrating data between clusters. | **Elasticsearch:** data store, migration, data lifecycle
**Ingest:** ingesting data into Elasticsearch
**Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools. | -| **Explore and analyze** | Content in this section focuses on querying, visualizing, and exploring data. Additionally it focusing on leveraging machine learning for data analysis and defining and responding to alerts | **Elasticsearch:** query languages, scripting, machine learning (NLP)
**Machine Learning:** Anomaly detection, data frame analytics, NLP
**Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools.
**ResponseOps:** Alerts and Cases | -| **Deploy and manage** | Content in this section focuses on evaluating deployment options and setting your environment up. This section also contains content around managing, securing, and monitoring your cluster. | **Elasticsearch:** deploying elastic, production guidance, security, and Management
**Cloud:** deploying and managing Elastic Cloud, Elastic Cloud Enterprise, Serverless, and ECK. | -| **Manage your Cloud account** | Content in this section focuses specifically on managing Cloud accounts. | **Cloud:** Managing your cloud account | -| **Troubleshoot** | Content in this section is troubleshooting content for the different products as well as how to contact support. | All troubleshooting content | -| **Extend and contribute** | Content in this section focuses on contributing to Elastic products and building plugins, clients, and beats modules. | **Contributions guides for:** Kibana Logstash Beats
**Developer guides for:** Integrations Elasticsearch Plugins | -| **Reference** | Content in this section focuses on manuals for optional products as well as reference materials like query language references, configuration references, etc. | Reference content, Release notes, Developer guide | - ## Report a bug * It's a **documentation** problem --> [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml) *or* [Fix it myself](locally.md) From 280115e71426f0654ffc5a17150ba6b8b6c9d5e8 Mon Sep 17 00:00:00 2001 From: George Wallace Date: Fri, 18 Apr 2025 15:31:43 -0600 Subject: [PATCH 12/13] Apply suggestions from code review Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com> --- docs/contribute/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/contribute/index.md b/docs/contribute/index.md index f10bfac17..6c878ed98 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -16,17 +16,17 @@ The version of the docs you want to contribute to determines the tool and syntax To contribute to earlier versions of the documentation, you must work with our [legacy documentation build system](https://github.com/elastic/docs). This system uses the [AsciiDoc](https://asciidoc.org) markup language. -* For **simple bugfixes and enhancements** --> [Contribute on the web](on-the-web.md) -* For **complex or multi-page updates** --> See the [legacy documentation build guide](https://github.com/elastic/docs?tab=readme-ov-file#building-documentation) +* For **simple bug fixes and enhancements**, refer to [Contribute on the web](on-the-web.md) +* For **complex or multi-page updates**, refer to our [legacy Building documentation guide](https://github.com/elastic/docs?tab=readme-ov-file#building-documentation) If you need to update documentation for both 8.x and 9.x, you will have to work in two systems. See [What if I need to update both 8.x and 9.x docs?](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/contribute/on-the-web#what-if-i-need-to-update-both-8.x-and-9.x-docs) for the processes on updating docs across different versions. ### Contribute to version `9.0+`, `ECE 4.0+`, and `ECK 3.0+` docs and later To contribute to `9.0+`, `ECE 4.0+`, and `ECK 3.0+` content, you need to work with our new documentation system. This system uses custom [Markdown syntax](../syntax/index.md). -This content lives in one of three places: +The source files for this content are hosted in one of three places: -1. **Reference/settings content** lives in the new Markdown files in the code repo as it did pre 9.0. This enables folks to make updates that touch code and low-level docs in the same PR. +1. **Reference/settings content** is generally stored in markdown files in the relevant product repo. For example, the Elasticsearch configuration reference is stored in the [elastic/elasticsearch](https://github.com/elastic/elasticsearch/tree/main/docs) repo. This enables contributors to make updates that touch code and low-level docs in the same PR. 2. **Narrative/conceptual and overview content** lives in [elastic/docs-content](https://github.com/elastic/docs-content). For example, the [ES|QL overview](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/explore-analyze/query-filter/languages/esql) lives in the **Explore & Analyze** section of the narrative docs. But the reference documentation lives in the Elasticsearch reference section of the docs: [ES|QL reference](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/esql) 3. **API reference docs** live in the different OpenAPI spec repositories. This is where you need to update API docs published in the new API docs system. From 223a3d378ea75fdb2962b15c2eef9050d71ee6ee Mon Sep 17 00:00:00 2001 From: George Wallace Date: Fri, 18 Apr 2025 15:35:18 -0600 Subject: [PATCH 13/13] Update contribution guide for documentation versions --- docs/contribute/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/contribute/index.md b/docs/contribute/index.md index 6c878ed98..f4b640f32 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -12,6 +12,8 @@ Whether you're a technical writer or you've only edited Elastic docs once or twi The version of the docs you want to contribute to determines the tool and syntax you must use to update the docs. The easiest way to find the source file for the page you want to update is to navigate to the page on the web and click **Edit this page**. This will take you to the source file in the correct repo. For more detailed instructions, see [Contribute on the web](on-the-web.md). +If you need to update documentation for both 8.x and 9.x, you will have to work in two systems. See [What if I need to update both 8.x and 9.x docs?](on-the-web.md#what-if-i-need-to-update-both-8.x-and-9.x-docs) for the processes on updating docs across different versions. + ### Contribute to version `8.18`, `ECE 3.8`, and `ECK 2.0` docs and earlier To contribute to earlier versions of the documentation, you must work with our [legacy documentation build system](https://github.com/elastic/docs). This system uses the [AsciiDoc](https://asciidoc.org) markup language. @@ -19,15 +21,13 @@ To contribute to earlier versions of the documentation, you must work with our [ * For **simple bug fixes and enhancements**, refer to [Contribute on the web](on-the-web.md) * For **complex or multi-page updates**, refer to our [legacy Building documentation guide](https://github.com/elastic/docs?tab=readme-ov-file#building-documentation) -If you need to update documentation for both 8.x and 9.x, you will have to work in two systems. See [What if I need to update both 8.x and 9.x docs?](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/contribute/on-the-web#what-if-i-need-to-update-both-8.x-and-9.x-docs) for the processes on updating docs across different versions. - ### Contribute to version `9.0+`, `ECE 4.0+`, and `ECK 3.0+` docs and later To contribute to `9.0+`, `ECE 4.0+`, and `ECK 3.0+` content, you need to work with our new documentation system. This system uses custom [Markdown syntax](../syntax/index.md). The source files for this content are hosted in one of three places: 1. **Reference/settings content** is generally stored in markdown files in the relevant product repo. For example, the Elasticsearch configuration reference is stored in the [elastic/elasticsearch](https://github.com/elastic/elasticsearch/tree/main/docs) repo. This enables contributors to make updates that touch code and low-level docs in the same PR. -2. **Narrative/conceptual and overview content** lives in [elastic/docs-content](https://github.com/elastic/docs-content). For example, the [ES|QL overview](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/explore-analyze/query-filter/languages/esql) lives in the **Explore & Analyze** section of the narrative docs. But the reference documentation lives in the Elasticsearch reference section of the docs: [ES|QL reference](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/esql) +2. **Narrative/conceptual and overview content** lives in [elastic/docs-content](https://github.com/elastic/docs-content). For example, the [ES|QL overview](https://www.elastic.co/docs/explore-analyze/query-filter/languages/esql) lives in the **Explore & Analyze** section of the narrative docs. But the reference documentation lives in the Elasticsearch reference section of the docs: [ES|QL reference](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/esql) 3. **API reference docs** live in the different OpenAPI spec repositories. This is where you need to update API docs published in the new API docs system. When you are ready to edit the content: