Skip to content

Commit d3596b8

Browse files
authored
Edit readme and add license (#229)
* Edit readme and add license * Complete guide * Update CONTRIBUTE.md * Whitespaces
1 parent 729d8ab commit d3596b8

File tree

5 files changed

+881
-132
lines changed

5 files changed

+881
-132
lines changed

CONTRIBUTE.md

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
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

Comments
 (0)