|
| 1 | +# Contributing to the EDOT docs |
| 2 | + |
| 3 | +This repository contains the EDOT documentation. We welcome pull requests. |
| 4 | + |
| 5 | +## Format and syntax |
| 6 | + |
| 7 | +The docs are written in the CommonMark flavor of Markdown. The Elastic V3 docs system also has a number of directives that allow you to create tabbed content, admonitions, stepped instructions, and much more. |
| 8 | + |
| 9 | +Refer to [Syntax guide](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/syntax/) for a detailed overview. |
| 10 | + |
| 11 | +## Structure |
| 12 | + |
| 13 | +All docs live in the `./docs` directory. The `./olddocs` repository contains redirections for the old docs and should not be touched. |
| 14 | + |
| 15 | +The docs are organized in the following directories: |
| 16 | + |
| 17 | +``` |
| 18 | +docs |
| 19 | +└── reference # Contains reference docs |
| 20 | + ├── _snippets # Reusable snippets |
| 21 | + ├── architecture # Architecture section |
| 22 | + ├── compatibility # Compatibility and support |
| 23 | + ├── edot-collector # EDOT Collector |
| 24 | + ├── edot-sdks # EDOT SDKs |
| 25 | + ├── images # Images |
| 26 | + ├── quickstart # Quickstarts |
| 27 | + └── use-cases # Use cases |
| 28 | +``` |
| 29 | + |
| 30 | +This structure might evolve as we refine the EDOT documentation according to the new V3 information architecture. |
| 31 | + |
| 32 | +## Style guide |
| 33 | + |
| 34 | +Elastic docs strive to keep a consistent voice and tone, with a distinct style throughout all repositories. |
| 35 | + |
| 36 | +Tech writers will help you refine your contributions. Refer to [Technical writing style guide](https://docs.elastic.dev/tech-writing-guidelines/home) to learn more. |
| 37 | + |
| 38 | +Always use US English spellings. |
| 39 | + |
| 40 | +## Terminology |
| 41 | + |
| 42 | +Use the following terms consistently and respect capitalization. |
| 43 | + |
| 44 | +| Term | Description | Alias | Example | |
| 45 | +|---|---|---|---| |
| 46 | +| **Elastic Distributions of OpenTelemetry** | Use to describe all distributions built by Elastic collectively | EDOTs | Use one of the Elastic Distributions of OpenTelemetry (EDOTs) in your application. EDOTs include... | |
| 47 | +| **Elastic Distributions of OpenTelemetry language SDKs** | Use to describe the collection of all the Elastic distributions that extend language SDKs (i.e. the APM-related distros) | EDOT language SDKs | With the Elastic Distributions of OpenTelemetry (EDOT) language SDKs you have access to all the features of the OpenTelemetry SDK that it customizes, plus... | |
| 48 | +| **Elastic Distribution of OpenTelemetry {language}** | Use to refer to a specific language distribution | EDOT {language} | The Elastic Distribution of OpenTelemetry (EDOT) Java is a Java package that provides an easy way to instrument your application with OpenTelemetry and configuration defaults for best usage. EDOT Java is a wrapper around... | |
| 49 | +| **Elastic Distribution of OpenTelemetry Collector** | Use to describe the customized version of the OpenTelemetry Collector that is built and maintained by Elastic | EDOT Collector | This guide shows you how to use the Elastic Distribution of OpenTelemetry (EDOT) Collector. The EDOT Collector sends logs and host metrics to Elastic Cloud. | |
| 50 | +| **Upstream** | Use to describe the upstream OpenTelemetry solutions. Do not use "vanilla" or other terms. | | The upstream OpenTelemetry Collector is maintained by the OpenTelemetry community. | |
| 51 | +| **Collector** | Use it to refer to any Collector instance, either upstream or EDOT. Always capitalize Collector when referring to the technical solution. Use lowercase when referring to multiple collectors. | | Deploy a Collector to receive and process telemetry data. Multiple collectors can be used for scaling. | |
| 52 | + |
| 53 | +Keep these rules in mind when using EDOT terms: |
| 54 | + |
| 55 | +* Always use the full product name the first time you refer to the product on each page. |
| 56 | +* Always establish the acronym for the product name (for example, EDOT) the first time it is mentioned in the body text. |
| 57 | + * Note: Do *not* establish the acronym for the first time in the page title or in a heading. If a heading comes *after* the first time the acronym is established in the body text, then it's ok to use the acronym instead of the full product name in the heading. |
| 58 | +* Avoid overusing the full product name. Use the shorter, already-established alias. |
| 59 | + |
| 60 | +## Frontmatter |
| 61 | + |
| 62 | +Each document must have the following frontmatter fields defined: |
| 63 | + |
| 64 | +```yaml |
| 65 | +--- |
| 66 | +navigation_title: Title for the sidebar |
| 67 | +description: Description for search engines. |
| 68 | +applies_to: # See https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/syntax/applies |
| 69 | + stack: |
| 70 | + serverless: |
| 71 | + observability: |
| 72 | +products: # See https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/syntax/frontmatter#products |
| 73 | + - id: cloud-serverless |
| 74 | + - id: observability |
| 75 | +--- |
| 76 | +``` |
| 77 | + |
| 78 | +## Linking other documents |
| 79 | + |
| 80 | +To link other Elastic docs, use [Cross-links](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/syntax/links#cross-repository-links). |
| 81 | + |
| 82 | +You can use relative links when linking other pages within the docs. |
| 83 | + |
| 84 | +## Building and previewing the docs site locally |
| 85 | + |
| 86 | +Pull requests automatically generate a preview environment. To build the docs locally, use the `docs-builder` tool. |
| 87 | + |
| 88 | +Refer to [Contribute locally](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/contribute/locally) for instructions on how to install and use `docs-builder`. |
0 commit comments