You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Aug 16, 2022. It is now read-only.
This repository contains the documentation for Open Distro for Elasticsearch, a full-featured, open source distribution of Elasticsearch for analytics workloads. You can find the rendered documentation at [opendistro.github.io/for-elasticsearch-docs/](https://opendistro.github.io/for-elasticsearch-docs/).
4
4
5
+
Developer and community contributions remain essential in keeping this documentation comprehensive, useful, organized, and up-to-date.
5
6
6
-
## Build
7
+
8
+
## How you can help
9
+
10
+
- Do you work on one of the various ODFE plugins? Take a look at the documentation for the plugin. Is everything accurate? Will anything change in the near future?
11
+
12
+
Often, engineering teams can keep existing documentation up-to-date with minimal effort, thus freeing up the documentation team to focus on larger projects.
13
+
14
+
- Do you have expertise in a particular area of Elasticsearch? Cluster sizing? The query DSL? Painless scripting? Aggregations? JVM settings? Take a look at the [current content](https://opendistro.github.io/for-elasticsearch-docs/docs/elasticsearch/) and see where you can add value. The [documentation team](#points-of-contact) is happy to help you polish and organize your drafts.
15
+
16
+
- Are you a Kibana expert? How did you set up your visualizations? Why is a particular dashboard so valuable to your organization? We have [literally nothing](https://opendistro.github.io/for-elasticsearch-docs/docs/kibana/) on how to use Kibana, only how to install it.
17
+
18
+
- Are you a web developer? Do you want to add an optional dark mode to the documentation? A "copy to clipboard" button for our code samples? Other improvements to the design or usability? See [major changes](#major-changes) for information on building the website locally.
19
+
20
+
- Our [issue tracker](https://github.com/opendistro/for-elasticsearch-docs/issues) contains documentation bugs and other content gaps, some of which have colorful labels like "good first issue" and "help wanted."
21
+
22
+
23
+
## Points of contact
24
+
25
+
If you encounter problems or have questions when contributing to the documentation, these people can help:
After each commit to this repository, GitHub Pages automatically uses [Jekyll](https://jekyllrb.com) to rebuild the [website](https://opendistro.github.io/for-elasticsearch-docs/). The whole process takes around 20 seconds.
35
+
36
+
This repository contains many [Markdown](https://guides.github.com/features/mastering-markdown/) files in the `/docs` directory. Each Markdown file correlates with one page on the website. For example, the Markdown file for [this page](https://opendistro.github.io/for-elasticsearch-docs/docs/elasticsearch/) is [here](https://github.com/opendistro/for-elasticsearch-docs/blob/master/docs/elasticsearch/index.md).
37
+
38
+
Using plain text on GitHub has many advantages:
39
+
40
+
- Everything is free, open source, and works on every operating system. Use your favorite text editor, Ruby, Jekyll, and Git.
41
+
- Markdown is easy to learn and looks good in side-by-side diffs.
42
+
- The workflow is no different than contributing code. Make your changes, build locally to check your work, and submit a pull request. Reviewers check the PR before merging.
43
+
- Alternatives like wikis and WordPress are full web applications that require databases and ongoing maintenance. They also have inferior versioning and content review processes compared to Git. Static websites, such as the ones Jekyll produces, are faster, more secure, and more stable.
44
+
45
+
In addition to the content for a given page, each Markdown file contains some Jekyll [front matter](https://jekyllrb.com/docs/front-matter/). Front matter looks like this:
46
+
47
+
```
48
+
---
49
+
layout: default
50
+
title: Alerting Security
51
+
nav_order: 10
52
+
parent: Alerting
53
+
has_children: false
54
+
---
55
+
```
56
+
57
+
If you're making [trivial changes](#trivial-changes), you don't have to worry about front matter.
58
+
59
+
If you want to reorganize content or add new pages, keep an eye on `has_children`, `parent`, and `nav_order`, which define the hierarchy and order of pages in the lefthand navigation. For more information, see the documentation for [our upstream Jekyll theme](https://pmarsceill.github.io/just-the-docs/docs/navigation-structure/).
60
+
61
+
62
+
## Contribute content
63
+
64
+
There are three ways to contribute content, depending on the magnitude of the change.
65
+
66
+
-[Trivial changes](#trivial-changes)
67
+
-[Minor changes](#minor-changes)
68
+
-[Major changes](#major-changes)
69
+
70
+
71
+
### Trivial changes
72
+
73
+
If you just need to fix a typo or add a sentence, this method works well:
74
+
75
+
1. In your web browser, navigate to the appropriate Markdown file. For example, [cluster.md](https://github.com/opendistro/for-elasticsearch-docs/blob/master/docs/elasticsearch/cluster.md).
76
+
77
+
1. Click the **Edit this file** button (the pencil).
78
+
79
+
1. Make your changes.
80
+
81
+
1. Choose **Create a new branch for this commit and start a pull request** and **Commit changes**.
82
+
83
+
84
+
### Minor changes
85
+
86
+
If you want to add a few paragraphs across multiple files and are comfortable with Git, try this approach:
87
+
88
+
1. Fork this repository.
89
+
90
+
1. Download [GitHub Desktop](https://desktop.github.com), install it, and clone your fork.
91
+
92
+
1. Navigate to the repository root.
93
+
94
+
1. Create a new branch.
95
+
96
+
1. Edit the Markdown files in `/docs`.
97
+
98
+
1. Commit, push your changes to your fork, and submit a pull request.
99
+
100
+
101
+
### Major changes
102
+
103
+
If you're making major changes to the documentation and need to see the rendered HTML before submitting a pull request, here's how to build locally:
104
+
105
+
1. Fork this repository.
106
+
107
+
1. Download [GitHub Desktop](https://desktop.github.com), install it, and clone your fork.
7
108
8
109
1. Navigate to the repository root.
9
110
@@ -30,21 +131,67 @@ This repository contains the documentation for Open Distro for Elasticsearch, a
30
131
1. Build:
31
132
32
133
```
33
-
bundle exec jekyll serve
134
+
sh build.sh
34
135
```
35
136
36
-
Alternately, run `build.sh`, which includes some convenience flags, is faster to type, and opens a live preview automatically.
137
+
1. If the build script doesn't automatically open your web browser (it should), open [http://localhost:4000/for-elasticsearch-docs/](http://localhost:4000/for-elasticsearch-docs/).
If you're a web developer, you can customize `_layouts/default.html` and `_sass/custom/custom.scss`.
42
144
43
-
1. Fork this repository.
44
-
1. Clone your fork.
45
-
1. Edit the Markdown files in `/docs`.
46
-
1. Use Jekyll to build the content, and make sure your changes render the way you expect.
47
-
1. Push your changes, and submit a pull request.
145
+
1. When you save a file, marvel as Jekyll automatically rebuilds the site and refreshes your web browser. This process takes roughly 20 seconds.
146
+
147
+
1. When you're happy with how everything looks, commit, push your changes to your fork, and submit a pull request.
148
+
149
+
150
+
## Writing tips
151
+
152
+
1. Try to stay consistent with existing content and consistent within your new content. Don't call the same plugin KNN, k-nn, and k-NN in three different places.
153
+
154
+
1. Shorter paragraphs are better than longer paragraphs. Use headers, tables, lists, and images to make your content easier for readers to scan.
155
+
156
+
1. Use **bold** for user interface elements, *italics* for key terms or emphasis, and `monospace` for Bash commands, file names, REST paths, and code.
157
+
158
+
1. Markdown file names should be all lowercase, use hyphens to separate words, and end in `.md`.
159
+
160
+
1. Don't use future tense. Use present tense.
161
+
162
+
**Bad**: After you click the button, the process will start.
163
+
164
+
**Better**: After you click the button, the process starts.
165
+
166
+
1. "You" refers to the person reading the page. "We" refers to the ODFE contributors.
167
+
168
+
**Bad**: Now that we've finished the configuration, we have a working cluster.
169
+
170
+
**Better**: At this point, you have a working cluster, but we recommend adding dedicated master nodes.
171
+
172
+
1. Don't use "this" and "that" to refer to something without adding a noun.
173
+
174
+
**Bad**: This can cause high latencies.
175
+
176
+
**Better**: This additional loading time can cause high latencies.
177
+
178
+
1. Use active voice.
179
+
180
+
**Bad**: After the request is sent, the data is added to the index.
181
+
182
+
**Better**: After you send the request, the Elasticsearch cluster indexes the data.
183
+
184
+
1. Introduce acronyms before using them.
185
+
186
+
**Bad**: Reducing customer TTV should accelerate our ROIC.
187
+
188
+
**Better**: Reducing customer time to value (TTV) should accelerate our return on invested capital (ROIC).
189
+
190
+
1. Spell out one through nine. Start using numerals at 10. If a number needs a unit (GB, pounds, millimeters, kg, celsius, etc.), use numerals, even if the number if smaller than 10.
191
+
192
+
**Bad**: 3 kids looked for thirteen files on a six GB hard drive.
193
+
194
+
**Better**: Three kids looked for 13 files on a 6 GB hard drive.
48
195
49
196
50
197
## New releases
@@ -66,15 +213,7 @@ This repository contains the documentation for Open Distro for Elasticsearch, a
66
213
1. Submit a PR.
67
214
68
215
69
-
## Content guidelines
70
-
71
-
1. Try to stay consistent with existing content.
72
-
1. Introduce acronyms before using them.
73
-
1. Use **bold** for user interface elements, *italics* for key terms or emphasis, and `monospace` for Bash commands, file names, URIs, and code.
74
-
1. Markdown file names should be all lowercase, use hyphens to separate words, and end in `.md`.
75
-
76
-
77
-
## Markdown guidelines
216
+
## Classes within Markdown
78
217
79
218
This documentation uses a modified version of the [just-the-docs](https://github.com/pmarsceill/just-the-docs) Jekyll theme, which has some useful classes for labels and buttons:
80
219
@@ -95,26 +234,22 @@ These classes can help with readability, but should be used *sparingly*. Each ad
95
234
96
235
Besides, standard Markdown elements suffice for most documentation.
97
236
98
-
To create an auto-generated table of contents near the top of long pages, use the following snippet:
237
+
238
+
## Math
239
+
240
+
If you want to use the sorts of pretty formulas that [MathJax](https://www.mathjax.org) allows, add `has_math: true` to the Jekyll page metadata. Then insert LaTeX math into HTML tags with the rest of your Markdown content:
99
241
100
242
```
101
-
#### Table of contents
102
-
1. TOC
103
-
{:toc}
104
-
```
243
+
## Math
105
244
106
-
By design, only `h2` and `h3` headers are included.
245
+
Some Markdown paragraph. Here's a formula:
107
246
108
-
If you create a new directory, name its first file `index.md` and make it a parent so that the links stay pretty:
247
+
<p>
248
+
When \(a \ne 0\), there are two solutions to \(ax^2 + bx + c = 0\) and they are
249
+
\[x = {-b \pm \sqrt{b^2-4ac} \over 2a}.\]
250
+
</p>
109
251
110
-
```
111
-
---
112
-
layout: default
113
-
title: Some New Page
114
-
nav_order: 4
115
-
has_children: true
116
-
has_toc: false
117
-
---
252
+
And back to Markdown.
118
253
```
119
254
120
255
@@ -135,4 +270,4 @@ See the [LICENSE](./LICENSE) file for our project's licensing. We will ask you t
135
270
136
271
## Copyright
137
272
138
-
Copyright 2019 Amazon.com, Inc. or its affiliates. All rights reserved.
273
+
Copyright Amazon.com, Inc. or its affiliates. All rights reserved.
0 commit comments