drafting where to work #768
Conversation
There was a problem hiding this comment.
Pull Request Overview
This pull request adds a new documentation page outlining guidelines for determining where to make contributions across various Elastic product areas.
- Introduces an overview of contribution pathways for content based on version (9.0+ vs. pre-9.0)
- Details product-specific sections for Kibana, Elasticsearch, Cloud, and Machine Learning
- Provides a mapping table for IA sections to product areas
docs/contribute/where-to-work.md
Outdated
|
|
||
| 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 |
There was a problem hiding this comment.
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
If this content is going to persist as a public-facing document that we point all external and internal contributors to, I'm happy to beef up the "how to contribute to API docs" content here too.
docs/contribute/where-to-work.md
Outdated
|
|
||
| ### **Kibana** | ||
|
|
||
| #### **What has moved to elastic/docs-content?** |
There was a problem hiding this comment.
What has moved to elastic/docs-content?
IMO this feels like info that's only really relevant for internal contributors and overcomplicates things for external contributors. Is it worth splitting this content into separate sections aimed at external contributors (i.e. as simple as possible, open issue or click edit link) and internal contributors (i.e. where did the files I used to have go? how do I backport? etc)
There was a problem hiding this comment.
I kinda agree but I guess we have a lot of external contributors who will also be confused by the changes, so maybe it makes sense. Not sure!
georgewallace
force-pushed
the
where-to-work
branch
from
d4c00c3 to
2d9cf90
Compare
There was a problem hiding this comment.
I have some minor comments/suggestions. 🤓
Bigger picture, the page has multiple sections at the same level without clear visual separation. It kinda feels like a wall of text. Maybe add a few emojis or callouts for visual distinction.
I'd also reorder the sections a bit because it feels a little disjointed right now:
- Contribute to docs
- Where does the content live
- Mapping sections to product areas
- Report a bug
- Request an enhancement
- Work on docs-builder
This puts all the informational content together first, followed by all the action-oriented sections at the end.
Co-authored-by: Liam Thompson <[email protected]>
Co-authored-by: Liam Thompson <[email protected]>
docs/contribute/index.md
Outdated
| | **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 <br>**Observability:** core observability content <br>**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 <br>**Ingest:** ingesting data into Elasticsearch <br>**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) <br>**Machine Learning:** Anomaly detection, data frame analytics, NLP <br>**Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools. <br>**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 <br>**Cloud:** deploying and managing Elastic Cloud, Elastic Cloud Enterprise, Serverless, and ECK. | |
There was a problem hiding this comment.
this "cloud" grouping is imprecise - these were originally built from 3 repos already
Co-authored-by: shainaraskas <[email protected]>
| ### 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). |
There was a problem hiding this comment.
this list is still incomplete - we have other versioning structures in play. this is the full list
https://www.elastic.co/docs/get-started/versioning-availability#find-docs-for-your-product-version
| ### 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). |
There was a problem hiding this comment.
this list is still incomplete - we have other versioning structures in play. this is the full list
https://www.elastic.co/docs/get-started/versioning-availability#find-docs-for-your-product-version
No description provided.