diff --git a/contribute-docs/good-issues.md b/contribute-docs/good-issues.md new file mode 100644 index 0000000000..df6094d2d3 --- /dev/null +++ b/contribute-docs/good-issues.md @@ -0,0 +1,84 @@ +--- +navigation_title: Create good issues +--- + +# How to create good docs issues + +We’re eager to help you. The best way to get our help is by creating a documentation issue. The following guidelines explain how to create documentation issues that we can act upon with minimal effort from you. + +## Before creating an issue + +### Check for existing documentation + +We are constantly improving our docs search and navigation. Before opening an issue about a missing piece of content, try the docs search or the navigation. + +### Make sure the issue is still relevant + +If you are creating an issue based on an old support case or a long-standing problem, validate that it is still relevant. Has the product or documentation changed since the original report? + +### Validate technical details + +If your request requires technical review or input, try to validate the details before opening the issue. For external contributors, provide as much context as possible in the issue description. For internal contributors, consider discussing with developers first to prevent the issue from being blocked indefinitely. + +## When creating an issue + +### Write a clear and specific title + +Titles help us identify and triage issues. The more specific they are, the better. If you’re creating an issue using the Report an issue link, edit the placeholder text. + +| ✅ Do this | ❌ Don't do this | +| ----- | ----- | +| *Add a new section on air-gapped configuration* | *Update docs* | +| *Website Link in EDOT logs tutorial is broken* | *Website some-doc-url* | +| *Python code snippet is not valid in tutorial X* | *This docs is wrong1!1* | + +### Formulate a clear request in the description + +Descriptions help us understand what needs to be changed in the docs. If there’s a template, strive to follow it. A good description contains a **definition of done** that describes the change you’d like to see. + +| ✅ Do this | ❌ Don't do this | +| ----- | ----- | +| *Update the installation methods table on the Elastic Agent page to include details on the new endpoint. Here is a sample config.* | *This doc must be improved.* | +| *Include a new table that outlines installation methods and upgradability for Elastic Agent.* | *There is no definition of done.* | +| *A customer had trouble with a recent Kafka change. Adding a note in the documentation would have helped them resolve their issue more quickly and prevented a support ticket.* | *There is no context nor a “why”.* | + +### Provide relevant links and resources + +When submitting requests or issues, include links to the impacted documentation pages and related tickets or discussions. + +#### Link to impacted documentation pages + +Include links to the relevant documentation pages that relate to your request or issue. + +#### Link to related tickets and discussions + +If your request relates to existing tickets or discussions, provide relevant links and context. + +For external contributors, include links to any public discussions, GitHub issues, forum posts, or blog posts that provide relevant background. + +For internal contributors, if your request stems from internal tickets or discussions, summarize the key points and mark any internal-only links clearly. If you need to provide sensitive context (such as UI copy for early-stage designs or billing changes), you can create an issue in the private repo, [elastic/docs-content-internal](https://github.com/elastic/docs-content-internal/issues/new/choose). Most issues should be opened in the public repo, [elastic/docs-content](https://github.com/elastic/docs-content/issues/new/choose). + +:::{tip} +**For internal contributors:** You can link to public docs issues from internal support cases and private issues. This adds a link to the docs issue's GitHub timeline for users within the Elastic org. +::: + +### Follow the issue templates + +The issue templates are there to help you provide the right information. You can always add more context if you want or modify the structure to suit your needs. + +### One issue = one single, testable problem + +Ideally, each ticket must represent a single, isolated problem or feature, or a bundle of closely related items. **Do not combine multiple bugs or requests into one ticket.** + +If your request is for a large project with many parts, reach out to the docs team to determine the scope and see how it’s best to chunk work. + +## Closing issues + +In general, we will ask for clarification if the issue has problems. **If our feedback is not addressed in a reasonable time, we might close the issue**. You can always reopen it after editing it. + +## Examples of great docs issues + +Here are some examples of excellent docs issues: + +- [Document Elastic Agent Upgrade Fails on Windows with status 0xc0000142](https://github.com/elastic/ingest-docs/issues/1775) +- [Prebuilt rule customization, upgrade, and export/import workflows](https://github.com/elastic/security-docs/issues/5061) diff --git a/contribute-docs/style-guide/accessibility.md b/contribute-docs/style-guide/accessibility.md new file mode 100644 index 0000000000..f5ba646df3 --- /dev/null +++ b/contribute-docs/style-guide/accessibility.md @@ -0,0 +1,243 @@ +--- +navigation_title: Accessibility and inclusivity +description: Guidelines for writing accessible and inclusive content. +--- + +# Accessibility + +These guidelines are intended for all content authors and contains common tips and tricks for writing accessible content. It is not exhaustive and does not replace the official [WCAG 2.0 guidelines](https://www.w3.org/TR/2008/REC-WCAG20-20081211/#guidelines). + +**Accessibility** for content means ensuring that all of our users can understand the content we publish—all of it—independently of how they choose or have to interact with it. + +Our users and readers are diverse, with different abilities and disabilities. +They also interact with our content in different ways, such as screen readers, mobile devices, and Braille. The list is long and constantly evolving. + +As content authors, it is our responsibility to provide them with [perceivable, operable, understandable, and robust content](https://www.w3.org/TR/UNDERSTANDING-WCAG20/intro.html#introduction-fourprincs-head). + +## Guidelines [accessibility-guidelines] + +✔️ **Make your content quickly scannable.** A clear structure and meaningful words will tell users if the content is relevant to them within seconds. Use unique headings, and put the most important information first. + +✔️ **Add alt text for all images, icons, and media files.** Screen readers, Braille output devices, and search engines love concise, accurate alt text that describes what cannot always be displayed, viewed, or heard on screen. + +:::{dropdown} Examples +✔️ **Do:** + +```md +![Signup page for Elastic Cloud](signup.png) +``` + +Note: Do not use special characters, such as backticks (`), in alt text. They are known to cause + formatting issues when building pages. + + For audio and videos, add captions and create scripts that describe the visual content. + Provide the script as a separate description track, either as timed text or recorded + narration. There are many free, easy-to-use tools available that support the process of + transcribing and captioning videos. For more information, refer to + [Creating Accessible Videos](https://www.washington.edu/accessibility/videos/). + +::: + +✔️ **Use plain language.** Users read our content to perform their tasks. Jargon and complex sentences will confuse them or, at best, slow them down. Expand acronyms when first written. You can find helpful, detailed plain language guidance on the [plainlanguage.gov](https://www.plainlanguage.gov/guidelines/) website. + +✔️ **Use parallel writing structures for similar things.** For example, don't use a combination of verbs and noun phrases to start each item in a list. Choose one or the other. + +:::{dropdown} Examples +❌ **Don't:** + +* Navigate Elastic Security's various tools and interfaces. +* Use Elastic Security's detection engine with custom and prebuilt rules. +* System requirements, workspaces, configuration, and data ingestion. + +✔️ **Do:** + +* Navigate Elastic Security's various tools and interfaces. +* Use Elastic Security's detection engine with custom and prebuilt rules. +* Learn about system requirements, workspaces, configuration, and data ingestion. + +::: + +✔️ **Use meaningful link text.** Descriptive text instead of "click here", "read more", or even a raw URL for a link makes it easier for users to understand what to expect when they open it. Screen +readers jump between links by generating a list of them, and spell out URLs. +:::{dropdown} Examples +❌ **Don't:** "[Click here](https://www.elastic.co) and make search your best ally." + +✔️ **Do:** "Visit [Elastic.co](https://www.elastic.co) and make search your best ally." + +::: + +✔️ **Use device-agnostic language when possible.** Users can access content and products in many ways. We do not know if they use a mouse, keyboard, tablet, or another device. +:::{dropdown} Examples +❌ **Don't:** "Enter a description and click the **Next** button." + +✔️ **Do:** "Enter a description and select **Next**." + +::: + +✔️ **Avoid directional language.** *Above*, *below*, *left*, *right*, and so on. All these terms assume that the layout never varies, that users actually see it, and that they see it the way you think they do. What about disabilities or responsiveness? +:::{dropdown} Examples + ❌ **Don't:** "Update your index mapping as you can see below to get the full benefit of + aggregating and searching for feature importance." + + ✔️ **Do:** "To benefit from aggregating and searching for feature importance, update your + index mapping as shown in this code example: [code example]" + +::: + +## Terms + +| Avoid | Use instead | +| ----- | ----------- | +| Click, tap | Select, choose | +| Above | Preceding, previous | +| Below, under | Following, further, later | +| See | Check, refer to | +| Hear (hear about) | Learn | + +## Testing content for accessibility + +Test as early and often as possible. It is always a good exercise to spot improvements early and develop good habits. +Here are a few methods that you can use to test content: + +**Navigate a website or app with only a keyboard** to ensure all content is accessible and +that a skip navigation link exists. + +**Test pages on mobile devices.** A growing number of users, including users with +disabilities, are accessing the web using phones, tablets, and other mobile devices. Test +your website using mobile devices, and when doing so, be sure to check for accessibility. + +You don't need an actual phone to do this. The Chrome dev tools, for example, are a precious ally to test various layouts. + +**Try a screen reader** to understand how users navigate websites using one of the screen +reader/browser combinations listed in the [Assistive technologies](#assistive-technologies) section. + +**Turn off speakers and microphones** to ensure the website experience is the same with +or without sound. + +## Assistive technologies + +Assistive technology allows individuals with disabilities to access +information technology and perform functions that might be otherwise impossible, like +reading text, navigating websites, or listening to a video. + +[Text-to-speech and screen readers](https://libguides.reading.ac.uk/inclusive-technology/text-to-speech) +read what's on your screen through the semantics placed in the content by developers. + +[Screen magnification software](https://www.afb.org/blindness-and-low-vision/using-technology/using-computer/part-ii-experienced-computer-user-new-0) +enlarges the monitor and makes reading easy for vision-impaired users. + +[The #NoMouse challenge](http://nomouse.org) provides guidance on navigating a +website using only the keyboard. Also, check out +[this list of special keyboards](https://bltt.org/keyboards-for-disabled-people/) made for +users with motor control difficulties. + +## Inclusivity + +These guidelines are intended for all content authors, whether you are a developer, designer, or writer. +This page is not exhaustive but provides some guidelines to write inclusive content for product content and technical documentation. + +**Inclusivity** for content means ensuring that the content we provide reflects the diversity of our community, respects it, and promotes positive change. + +### Guidelines [inclusivity-guidelines] + +### Write for an international audience + +Our products and documentation use American English (en_US) as a standard for written content. +Yet they are used and read by people all around the globe, for whom English is not always their primary language. +Our content must take that into account. + +✔️ **Aim for simplicity.** We are a technical company that writes for + technically savvy users. However, keeping our writing as simple as possible benefits everyone. + + * **Short sentences**: They leave less space for interpretation. They are easier to scan, read, and translate. + + * **Plain language**: Active voice, present tense, using examples, and so on. + Some of these guidelines might already look familiar. Several countries have [plain language initiatives](https://www.plainlanguage.gov/guidelines/) to promote clearer communication. + Do your best to embrace these guidelines and focus on the message. + We're not going for Scrabble high scores, and no one is carrying a thesaurus to read our docs. + Well, maybe the writers... + + * **Negation**: It is generally easier for everyone to say what something IS versus what it is NOT. + When you add a negative construction, it takes the reader longer to parse the meaning of the phrase. + Instead of saying, "You cannot access the content without signing up", it's much easier to read, "Sign up to access the content." + + * **Words with multiple meanings**: + Don't skip helper words if they make the sentence clearer or easier to read. + We try to be as literal and unambiguous as possible in our docs to ensure that our readers from around the globe can consume them. + One way to achieve that is to choose words with fewer meanings, especially when a word's intended meaning is not its primary meaning. + +:::{dropdown} Example + You may have noticed the rather poetic use of _consume_ in the + previous paragraph. While the use here is correct, it's somewhat figurative. Someone + looking up the term in an English dictionary may wonder why on Earth they should + want to _eat, drink, or ingest_ our documentation. + + A more subtle example of a multi-meaning term that appears very often in + technical documentation is the word _once_. For example: + + "Once Luke, Leia, Han, and Chewie have entered the trash compactor, press Start." + (_Death Star Reference Manual, V1.6, p.25_) + + The primary meaning of _once_ is _on one occasion_ or + _for one time only_. In this sentence, the term _after_ is preferable since it's unambiguous and, + therefore, easier for non-native English speakers and stormtroopers to + ~~consume~~ understand. +::: + +✔️ **Be aware of differences and diversity in content and examples.** +Different people are used to different names, currencies, date and time formats, different measurement units (such as for temperature, distance, speed), and so much more. + +* Avoid ambiguous values, like `04/05/06` for a date. Is it May 4 or April 5, and which year? `11/17/1987` leaves less room for interpretation if the exact format is not specified nearby. +* If there is no obvious example standard (RFC) to follow, try to be diverse to represent our audience. + +✔️ **Avoid idioms or expressions that are not commonly known, also known as regionalisms.** + +In our Elastic documentation, we aim for a fun, friendly, and sometimes quirky +tone. To achieve that, it can help to use informal, playful language. However, +we also have to be careful that our text is as inclusive as possible, so we try +to avoid expressions that might be unknown or opaque to some readers. Here are +a few examples of what to avoid: + +* Idioms (for example, _It's a piece of cake_ or _So far so good_) +* Regional expressions (for example, _G'day!_, _Y'all_, or _eh_) +* Sports expressions (for example, _touched base_ or _threw a curve ball_) +* Pop culture references (for example, _Elvis has left the building_ or _Same bat-time, same bat-channel_) + +We're all pretty good at avoiding these, but there's one problematic type of +expression that shows up frequently in docs reviews. Latin terms and +abbreviations are a common source of confusion, particularly for people whose +first language does not have Latin roots. + +Here are some terms to avoid and suggested alternatives: + +| Avoid | Use instead | +| ----- | ----------- | +| e.g. (exempli gratia) | For example | +| etc. (et cetera) | And more, and so on | +| i.e. (id est) | That is | +| via | By way of, by means of, through | + +✔️ **Aim for readability.** Tools like the Hemingway App can help you make content simpler. Be conversational, but prioritize clarity. + +#### Use gender-neutral language + +Writing gender-neutral mainly consists of avoiding gender bias and word choices implying that one gender is the norm. + +✔️ **Pronouns.** In technical documentation, you can avoid this most of the time by addressing users directly. +When it's not possible, use *they*/*their*, even for singular. There's more than one gender, and it's not binary, either. + +✔️ **Biased words and expressions.** Guys, mankind, policeman...these are all words we use and are used to hearing. But the default is not male. +Most expressions and words that perpetuate this bias (that exists in many cultures and languages!) can be replaced with neutral alternatives or synonyms: Folks, humanity, police officer... + +#### Avoid violent, offensive, ableist terminology + +Earlier in this page, we discussed avoiding ambiguous terms, especially when a word's intended meaning is +not its primary meaning. Other types of words and phrases best avoided are: + +* buzzwords (_incentivize_, _synergies_) +* superhero terms (_rockstar_, _wizard_, _ninja_) +* violent imagery (_crush the competition_) +* non-specific superlatives (_unrivaled_, _unparalleled_, _world class_) + +Some words have nuances that fall into the above categories, which might cause +them to be misinterpreted. For a full list, refer to [Word choice](word-choice.md). diff --git a/contribute-docs/style-guide/formatting.md b/contribute-docs/style-guide/formatting.md new file mode 100644 index 0000000000..819571b3da --- /dev/null +++ b/contribute-docs/style-guide/formatting.md @@ -0,0 +1,472 @@ +--- +navigation_title: Formatting +description: Guidelines for using consistent formatting across Elastic documentation. +--- + +# Formatting + +As technical writers and contributors, it's our job to design our documentation to be user-friendly, accessible, and efficient so users can find what they need quickly and comprehend what they read. Consistent formatting—especially for components that highlight relationships between concepts, such as headings, images, tables, and lists—can help achieve this. + +## Line spacing + +Enter a single line break between two elements, for example, between the end of a sentence and a new table. Unless it's required for Asciidoc, Markdown, or MDX syntax, you shouldn't need double spacing or indentation. Our stylesheets control the visual appearance of our docs, like font, colors, and sizing, so you don't have to worry about those, either. + +Use a single line break to control the spacing between paragraphs. In general, try to keep paragraphs short so users aren't overwhelmed with lengthy blocks of text. This is even more imperative if a user is on a mobile device. If your paragraph is more than seven lines, consider dividing it into two paragraphs. + +## Emphasis + +Bold, italic, and monospace formatting helps users distinguish words and phrases from the surrounding text and provides visual cues for users. + +Use emphasis only in the text body, and avoid using it in titles and links. All titles must appear uniform so that users can scan them in the table of contents. By default, links are emphasized by rendering in a different color. Avoid applying multiple variations of emphasis to the same text. For example, when link text includes the name of a UI element, avoid using bold. + +### Bold / strong + +Use bold text formatting to emphasize the names of UI elements so that users can identify interactive components. + +| Element | Example | +| ------- | ------- | +| Apps | **Visualize** allows you to create visualizations of the data in your Elasticsearch indices. | +| Columns | In the **Value** column, go to the value you want to edit and click **Edit**. | +| Interactive UI functions | To use a dark color theme, click **Options** and select **Use dark theme**. | +| Key combinations | Press **Alt+C**. | +| Menu items | In Kibana, open the main menu, then click **Discover**. | +| Page names | The **Hosts** page provides a comprehensive overview of all hosts and host-related security events. | +| Sections | The **Document Summary** section provides general alert details, including any available threat intelligence data. | +| Tables | In the **Value lists** table, click the value list you want to edit. | +| Tabs | The **Overview** tab provides an overview of the alert and shows relevant threat intelligence details. | + +If the name of the UI element isn't explicitly shown in the UI, then don't bold it. +::::{dropdown} Example +The risk summary table shows the category, score, and number of risk inputs that determine the host risk score. +:::: + +### Italic / emphasis + +Use italic text formatting to emphasize new words and concepts that are introduced to users for the first time, as well as titles of Elastic documentation resources. + +| Element | Example | +| ------- | ------- | +| Terms | A Metricbeat *module* defines the basic logic for collecting data from a specific service. | + +### Monospace / code + +Use monospace text formatting to emphasize technical elements to help users differentiate code and command examples from regular text. + +| API endpoints | The endpoints include `/_bulk` and `/INDEX/_bulk`. | +| --- | --- | +| Class names | Date fields are exposed as `ReadableDateTime`, so they support methods like `getYear`. | +| Code blocks | ```sh GET _tasks GET _tasks?nodes=nodeId1,nodeId2 GET _tasks?nodes=nodeId1,nodeId2&actions=cluster:* ``` | +| Command invocations | To create the basic files for your metricset, run `make create-metricset`. | +| Command names | The `elasticsearch-certutil` command simplifies the creation of certificates. | +| Configuration settings | For example, set `action.auto_create_index` to `+aaa*,-bbb*,+ccc*,-*`. | +| Data types | The example uses a strongly typed `int`. | +| Directory names and paths | The example harvests all files in the `/var/log/*.log` path. | +| Environment variables | Set the `ES_PATH_CONF` environment variable. | +| Error and validation messages | After you start Logstash, wait until you see `Pipeline main started`. | +| Field names | Filter by the `rule.section` field. | +| Function and method names | Date fields are exposed as `ReadableDateTime`, so they support methods like `getYear`. | +| Index names | The `.ml-notifications` index. | +| Inline code | To access the names, use `doc['first'].value` and `doc['last'].value`. | +| Parameter names | The query requires the `type` and `id` parameters. | +| Process names | Verify the `autodetect` process is running. | +| Property names | The following example uses the `DROP` command to omit the `_id` property from the results table. | +| Role names | The `kibana_system` role is required. | +| User input | In the command line, enter `hello world`. | +| Variables | Access the original source for a field as `ctx._source.`. | + + +## Lists and tables + +Lists and tables are an effective way to structure and organize data. Consider the following guidelines when deciding which of these components to use. + +Use a list: + +* If the order of items is important, such as for step-by-step instructions. +* If the items you're listing don't need to be directly compared. +* When each item includes a short description. + +Use a table: + +* If users need to compare several items and you want to present their differences and similarities. +* When each item consists of three or more pieces of related data, such as parameter name, type, and description. +* If there isn't a simpler way to present your content, such as in a list or paragraph text. + +## Lists + +Lists are an excellent way to present related or sequential data that's easy to scan. A list should have at least two list items. Here are some general rules to follow: + +* Introduce the list with a heading, a complete sentence, or a fragment that ends with a colon. +* Use parallel structures for list items. For example, don't use a combination of verbs and noun phrases to start each item in a list. Choose one or the other. +* Begin each list item with a capital letter (unless it's case-sensitive, such as a lowercase field or CLI command). +* Don't use a period at the end of list items unless they're complete sentences. +* If a list has run-in headings, end the run-in headings with a period or colon, and use bold formatting for them. + +In Elastic documentation, we typically use two types of lists: bulleted and numbered lists. + +### Bulleted lists + +Use a bulleted list to group related items that can appear in any order or to describe options that users can choose from. + +:::{dropdown} Examples + +Alert suppression allows you to reduce the number of repeated or duplicate detection alerts created by these detection rule types: + +* Custom query +* Threshold +* Indicator match +* Event correlation (non-sequence queries only) +* New terms + +--- + +To create the visualizations in this tutorial, you'll use the following fields: + +* `timestamp` +* `bytes` +* `referer.keyword` + +--- + +On the **Dashboards** page, choose one of the following options: + +* To start with an empty dashboard, click **Create dashboard**. +* To open an existing dashboard, click the dashboard **Title** you want to open. + +--- + +Templates can include two types of filters: + +* **Regular filter**: Like other Kibana KQL filters, defines both the source event field and its value. +* **Template filter**: Only defines the event field and uses a placeholder for the field's value. + +::: + +### Numbered lists + +Use a numbered list for a sequence of steps or a procedure that's performed in a specific order. + +:::{dropdown} Examples + +Sample data sets come with sample visualizations, dashboards, and more to help you explore Kibana before you ingest or add your own data. + +1. On the home page, click **Try sample data**. +1. Click **Other sample data sets**. +1. On the **Sample eCommerce orders** card, click **Add data**. + +--- + +When security is enabled, you grant users access to reporting features with Kibana application privileges. + +1. Enable application privileges in **Reporting**. +1. Create the reporting role. + 1. Open the main menu, then click **Stack Management**. + 1. Click **Roles → Create role**. +1. Specify the role settings. + 1. Enter the **Role name**. For example, `custom_reporting_user`. + 1. Specify the **Indices** and **Privileges**. +1. Add the Kibana privileges. +1. Click **Create role**. +1. Assign the reporting role to a user. + +--- + +#### How is risk score calculated? + +1. The risk scoring engine runs hourly to aggregate **Open** and **Acknowledged** alerts from the last 30 days. +1. The engine groups alerts by `host.name` or `user.name` and aggregates the individual alert risk scores. +1. The engine then verifies the entity's asset criticality level and updates the risk score based on this value. +1. Based on the two risk inputs, the risk scoring engine generates a single entity risk score of 0-100. + +::: + +## Tables + +We use tables to present structured data, so it's easier for users to scan and compare it. A table should have at least two rows (excluding the header) and at least two columns. Here are some general rules to follow: + +* Use a table header to explain what the rows and columns represent. +* Use parallel structures for table entries. For example, don't use a combination of verbs and noun phrases to start each table entry. Choose one or the other. +* Use sentence-style capitalization for table headers and table entries (unless they're case-sensitive, such as lowercase fields or CLI commands). +* Don't use a period at the end of table entries unless they're complete sentences. +* To give users context, introduce a table with a sentence that describes its purpose. +* Avoid overly complex tables with split or merged cells. If possible, use multiple tables instead. + +:::{dropdown} Examples + +To separate staging and production APM data, we need to create six filtered aliases—three aliases for each service environment: + +| Index setting | `production` environment | `staging` environment | +| ------------- | ------------------------ | --------------------- | +| Error | `production-logs-apm` | `staging-logs-apm` | +| Span/transaction | `production-traces-apm` | `staging-traces-apm` | +| Metrics | `production-metrics-apm` | `staging-metrics-apm` | + +::: + + +## Numbers + +Write out numbers 1–9, and numerals for numbers 10 and greater, except for tables, decimals, dimensions, and most percentages. + +When your sentence includes numbers that are both less than and greater than 10, use numerals for consistency. + +:::{dropdown} Examples + ❌ **Don't**: The watcher thread pool size is now five times the number of processors until 50 threads are reached. + + ✔️ **Do**: There are two ways to create and add panels. +::: + +### Separate large numbers with commas + +Use a comma separator to make it easy for users to quickly and easily read large numbers. + +:::{dropdown} Examples + ❌ **Don't**: 1234567 users + + ✔️ **Do**: 1,234,567 users +::: + +### Use numerals in tables + +When you add numbers to a table, use only numerals so that users can quickly analyze the information. + +:::{dropdown} Examples + + ❌ **Don't**: + + | Deployment | Instances | Nodes | + | ---------- | --------- | ----- | + | AWS | 20 | Seven | + | GCP | 45 | Three | + + ✔️ **Do**: + + | Deployment | Instances | Nodes | + | ---------- | --------- | ----- | + | AWS | 20 | 7 | + | GCP | 45 | 3 | + +::: + +### Decimals + +Use numerals for decimals and pluralize the noun. When decimal numbers are less than one, include the zero before the decimal point. + +:::{dropdown} Examples + ❌ **Don't**: One pixel + + ✔️ **Do**: 0.5 pixels +::: + +### Dimensions + +Use numerals for dimensions, separated by a lowercase *x* and without spaces. + +:::{dropdown} Examples + ❌ **Don't**: 16 X 9 + + ✔️ **Do**: 16x9 +::: + +### Percentages + +When using a percent in a sentence, use numerals and the percent sign, without a space. When starting a sentence with a percentage, write out the numeral and word percent. + +:::{dropdown} Examples + ❌ **Don't**: 30% of the memory must be free. + + ✔️ **Do**: Odds of a 0.50% increase are slim. + + ✔️ **Do**: Thirty percent of the memory must be free. +::: + +## Code samples + +Good code samples can be extremely valuable in developer documentation. They're a great way to illustrate how to implement specific features or functionality. Whenever possible, provide complete and runnable code samples that users can copy and test out themselves. + +In general, follow the formatting rules of the language of the code sample. + +The following guidelines will help to ensure your code samples are clear, readable, and easily understandable. + +### Use consistent indentation + +Use spaces, not tabs, to indent code. Make sure that indentation is consistent throughout the code sample. For example, use 2 spaces per indentation level for JSON examples. + +:::::{tip} + +You can use online tools such as [JSON formatter](https://jsonformatter.org) to validate and format your code examples. + +:::{dropdown} Example + +```json +{ + "rule_id": "process_started_by_ms_office_program_possible_payload", + "threat": [ + { + "framework": "MITRE ATT&CK", + "tactic": { + "id": "TA0001", + "reference": "https://attack.mitre.org/tactics/TA0001", + "name": "Initial Access" + }, + "technique": [ + { + "id": "T1193", + "name": "Spearphishing Attachment", + "reference": "https://attack.mitre.org/techniques/T1193" + } + ] + } + ] +} +``` +::: +::::: + +### Apply syntax highlighting + +Syntax highlighting improves readability of code samples by adding color highlighting relevant to the language of the sample. Where applicable, use the appropriate AsciiDoc or Markdown formatting for syntax highlighting. + +For AsciiDoc, samples should be preceded by `[source,{format}]`, where `format` is one of: +`console`, `console-result`, `eql`, `esql`, `java`, `js`, `json`, `ruby`, `sh`, `shell`, `term`, `text`, `xml`, `yaml`, `yml` + +:::{dropdown} Example + +```asciidoc +[source,yaml] +---- +path: + data: + - /mnt/elasticsearch_1 + - /mnt/elasticsearch_2 + - /mnt/elasticsearch_3 +---- +``` + +::: + +For Markdown, specify a language next to the backticks that precede the code block. + +:::{dropdown} Example + +````markdown +```yaml +path: + data: + - /mnt/elasticsearch_1 + - /mnt/elasticsearch_2 + - /mnt/elasticsearch_3 +``` +```` + +::: + +### Add comments and explanations + +Where needed, you can include comments in code samples to explain specific parts of the code. To do this, use the comment syntax of the language of your code sample. For example, for single-line comments in Java, use two forward slashes (`//`). Add the comment before the line or group of lines it refers to. + +:::{dropdown} Example + +```java +WatcherBuild build = watcherStatsResponse.getBuild(); + +// The current size of the watcher execution queue +long executionQueueSize = watcherStatsResponse.getThreadPoolQueueSize(); + +// The maximum size the watcher execution queue has grown to +long executionQueueMaxSize = watcherStatsResponse.getThreadPoolQueueSize(); + +// The total number of watches registered in the system +long totalNumberOfWatches = watcherStatsResponse.getWatchesCount(); + +// Watcher state (STARTING, STOPPED or STARTED) +WatcherState watcherState = watcherStatsResponse.getWatcherState(); +``` + +::: + +For languages that don't support comments natively, such as JSON, you can add explanations about specific lines using [footnotes](./formatting.md). + +:::{dropdown} Example + +```json +{ + "_tags": [ + "endpoint", <1> + "os:windows" <2> + ], + "comments": [], + "description": "File exception for Windows", + "entries": [ + { + "field": "file.hash.sha1", + "operator": "included", + "type": "match", + "value": "27fb21cf5db95ffca43b234affa99becc4023b9d" + } + ], + "item_id": "trusted-windows-file", + "list_id": "endpoint-exception-container", + "name": "Trusted Windows file", + "namespace_type": "agnostic", <3> + "tags": [], + "type": "simple" +} +``` +1. Indicates this item is for endpoint rules. +2. Relevant OS. +3. Item accessible from all Kibana spaces. + +::: + +## Footnotes + +A footnote is an annotation with additional information usually provided at the end of a page, section, or code sample. In general, avoid footnotes because they aren't accessible. + +Instead of a footnote, consider adding a link or putting the information in an admonition, like a note. If you _must_ use a footnote—for example, if you need to add a comment in a language that doesn't support them natively, like JSON—follow these guidelines: + +* Keep footnotes short and concise. +* If you have more than one footnote, number them in sequential order. +* Offset the numeral with superscript. + +## Redaction of sensitive information + +End-user documentation may contain screen captures and examples that show +real or realistic data. To prevent malicious actors from using this information +to attack Elastic systems, employees, partners, or customers, we must avoid +leaking sensitive information. + +Sensitive information might include: + +* Data about (or provided by) customers, including code samples and logs +* Data about Elastic employees or partners +* Passwords, tokens, or secrets +* Security certificates +* Host/port info about real systems +* Links to internal documents + +:::::{tip} + Fake security information is not considered sensitive, but may trigger alerts during scans. +::::: + +Common examples of leaked data include: + +* Screen captures that show employee or customer names and details +* Screen captures that expose user credentials or tokens +* Screen captures that show hostnames or IP addresses +* Example access logs that expose real data + +### How to protect sensitive information + +* Use a blur tool (or similar) to hide or mask sensitive data in screen +captures. +* Replace sensitive data in examples or text with generic, placeholder text. +For example: `myname@example.com:my-api-key`. +* Avoid showing realistic security data that might be flagged during scans. For +example, instead of showing a real web hook, use placeholder text: +`https://hooks.slack.com/services/T00000000/B00000000/` +* When possible, use domain names and IP addresses that are reserved for documentation. +For more information, refer to: + * [RFC2606 - Reserved Top Level DNS Names](https://datatracker.ietf.org/doc/html/rfc2606) + * [RFC5737 - IPv4 Address Blocks Reserved for Documentation](https://datatracker.ietf.org/doc/html/rfc5737) + * [RFC3849 - IPv6 Address Blocks Reserved for Documentation](https://datatracker.ietf.org/doc/html/rfc3849) + diff --git a/contribute-docs/style-guide/grammar-spelling.md b/contribute-docs/style-guide/grammar-spelling.md new file mode 100644 index 0000000000..927326f5e2 --- /dev/null +++ b/contribute-docs/style-guide/grammar-spelling.md @@ -0,0 +1,436 @@ +--- +navigation_title: Grammar and spelling +description: Guidelines for using correct grammar and spelling in your writing. +--- + +# Grammar and spelling + +## Pronouns do's and don'ts + +### Be unambiguous + +In order to make your sentences as clear as possible when using pronouns, they should always be unambiguous. + +Pronouns provide a wonderful kind of shorthand so that we don't need to repeat lengthy terms over and over. But they can also cause confusion. In the first sentence, readers might be puzzled about whether the pronoun *they* refers to *your sentences* or to *pronouns*. + +To remedy this, let's reorganize the sentence so that we don't need the *they* pronoun at all: + +"In order to make your sentences as clear as possible, avoid using ambiguous pronouns". + +And while we're at it, let's remove the *in order* since it doesn't really add anything: + +"To make your sentences as clear as possible, avoid using ambiguous pronouns". + +### Use second-person pronouns (*you*, *your*, *yours*) + +In general, write in the second person to establish a friendly, casual tone with the reader as though you're speaking to them. Writing in the second person also helps you avoid using passive voice. However, don't overuse *your* when referring to user interaction. + +For example: *Your Elastic Agents* can feel overly familiar if used too many times. However, *your environment* as opposed to *the environment* sounds more casual. It can be tricky when deciding word choice, but when in doubt, try replacing the pronoun with *the* to see if it's an appropriate substitute. + +:::{dropdown} Examples + * Log in to your account to display the settings. + * Verify that you have the correct permissions. +::: + +### Use singular first-person pronouns sparingly (*I*, *me*, *my*, *mine*) + +Typically, you should never write in the first person. You can, however, use first-person pronouns if they appear in the product UI. + +:::{dropdown} Example +Select the checkbox that says, "Confirm my selection." +::: + +### Use plural first-person pronouns wisely (*we*, *us*, *our*, *our*) + +First-person plural pronouns can sometimes convey a stuffy and serious tone—the opposite of Elastic's more casual tone. In some instances, however, it's okay to use these sparingly. For example, it's perfectly acceptable to say *we recommend*, and in fact is preferable over *it is recommended* since that uses passive voice. + +### Avoid gendered pronouns + +Use gender-neutral pronouns as appropriate. Avoid using *he*, *him*, *his*, *she*, and *her*. Instead, try replacing it with a form of *user*. Also, avoid using combination pronouns such as *he/she* or *(s)he*. Use *they* or *them* instead. + +## Verb tense + +Avoid temporal words like *currently*, *now*, or *will* and conditional words like *should* or *could*. Write in the present tense to describe the state of the product as it is now. You may need to use the past tense occasionally, but try to change it to the present tense to see if that's a better fit. + +:::{dropdown} Example +❌ **Don't**: If you didn't select all the required permissions, an error message will appear. + +✔️ **Do**: If you don't select all the required permissions, an error message appears. +::: + +## Contraction do's and dont's + +Use contractions: they're (an acceptable contraction, by the way) conversational and don't require a lot of thought because we use them in everyday language. However, don't mix contractions and their spelled-out equivalents. For example, don't use *don't* and *do not* in the same context unless you absolutely need the latter for emphasis. + +Don't use Elastic references as a contraction to replace *Elastic is*. + +:::{dropdown} Example +❌ **Don't**: Elastic's excited to release this new feature. + +✔️ **Do**: Elastic's new feature helps you find information fast. +::: + +Avoid ambiguous or awkward contractions, such as *there'd*, *it'll*, and *they'd*. + +## Gerunds + +A gerund is a verb form that ends in `-ing` and acts as a noun. Use gerunds or action verbs in titles that describe tasks. Use gerunds in top-level topic titles, but use action verbs in lower-level titles, especially in sections with many subtasks. + +:::{dropdown} Example + +Working with clusters + +Change your cluster configuration + +Keep your clusters healthy + +Secure your cluster + +::: + +Avoid gerunds in prepositional phrases—this will make your instructions easier to understand. Also avoid gerunds in instructional/procedural sentences or headings. + +:::{dropdown} Example +❌ **Don't**: Refer to instructions on configuring the Elastic Agent. + +✔️ **Do**: Refer to instructions on how to configure the Elastic Agent. +::: + +## Punctuation + +### Colons + +Use a colon at the end of a sentence or phrase that introduces a list. If a list item is followed by a description, use a colon to introduce the description. + +:::{dropdown} Example +Select one of the following alert actions: +* **Close this alert**: Closes the alert when the exception is added. This option is only available when adding exceptions from the Alerts table. +* **Close all alerts that match this exception and were generated by this rule**: Closes all alerts that match the exception's conditions and were generated only by the current rule. +::: + +### Commas + +Use commas: + +* Before the conjunction in a list of three or more items (also known as Oxford comma). + +:::{dropdown} Examples +* Supported providers are OpenAI, Azure OpenAI Service, and Amazon Bedrock. +* Follow the onboarding instructions in the getting started guides for AWS, GCP, or Azure. +::: + +* After an introductory word or phrase. + +:::{dropdown} Examples +* Generally, the monitoring cluster and the clusters being monitored should be running the same version. +* For additional context, alert events are stored in hidden Elasticsearch indices. +::: + +* To join independent clauses with a coordinating conjunction (*and*, *but*, *or*, *nor*, *fo*r, *so*, or *yet*). + +:::{dropdown} Examples +* A case can have multiple connectors, but only one connector can be selected at a time. +* Click **Add events**, and follow the links for the types of data you want to collect. +::: + +* When an adverbial dependent clause comes before an independent clause. + +:::{dropdown} Examples +* When creating exceptions, you can assign them to individual rules or to multiple rules. +* After rules have started running, you can monitor their executions to verify they are functioning correctly. +::: + +* To set off non-defining relative clauses (also known as non-restrictive or parenthetical clauses). + +:::{dropdown} Examples +* Missing fields get a `null` value, which is used to group and suppress alerts. +* The risk scoring engine calculates the user risk score for `User_A`, whose asset criticality level is **Extreme impact**. +::: + +❌ Don't use commas: + +* When an independent clause and a dependent clause are separated by a coordinating conjunction (*and*, *but*, *or*, *nor*, *fo*r, *so*, or *yet*). + +:::{dropdown} Examples +❌ **Don't**: The rule runs every 5 minutes, but analyzes the documents added to indices during the last 6 minutes. + +✔️ **Do**: The rule runs every 5 minutes but analyzes the documents added to indices during the last 6 minutes. + +❌ **Don't**: A custom query rule searches the defined indices, and creates an alert when a document matches the rule's KQL query. + +✔️ **Do**: A custom query rule searches the defined indices and creates an alert when a document matches the rule's KQL query. +::: + +* To set off defining relative clauses. + +:::{dropdown} Examples +❌ **Don't**: You must use a data view, whose index pattern matches `servers-europe-*`. + +✔️ **Do**: You must use a data view whose index pattern matches `servers-europe-*`. + +❌ **Don't**: To roll back, you must have a backup snapshot, that includes the `kibana` feature state. + +✔️ **Do**: To roll back, you must have a backup snapshot that includes the `kibana` feature state. +::: + +### Dashes and hyphens + +#### Hyphens + +Hyphens compound words, word elements, or numbers to change their meaning. + +Use a hyphen: + +* When a prefixed word has two vowels together. + +:::{dropdown} Examples + +* Re-enable +* Pre-approve +::: + +* When two or more words modify the following noun, making a compound adjective. + +:::{dropdown} Examples + +* Real-time results +* AI-generated text +* User-defined values +* Up-to-date environment +::: + +* Whenever the prefix is `self-`, `ex-`, or `all-`. + +:::{dropdown} Example + Self-managed deployment +::: + +* For a minus sign and to indicate negative numbers. In formulas and equations, add spacing between the numbers and arithmetic operators. For negative numbers, don't add spacing between the minus and the number. + +:::{dropdown} Examples + +* 12 - 3 = 9 +* -79 +::: + +❌ Don't use a hyphen: + +* For predicate adjectives (compound modifiers that come after the word they modify). + +:::{dropdown} Examples +❌ **Don't**: Ensure your environment is up-to-date. + +✔️ **Do**: Ensure your environment is up to date. + +❌ **Don't**: The values are user-defined. + +✔️ **Do**: The values are user defined. +::: + +* For compounds with an adverb ending in `-ly`. + +:::{dropdown} Examples +❌ **Don't**: Newly-installed Agent + +✔️ **Do**: Newly installed Agent + +❌ **Don't**: Publicly-exposed storage buckets + +✔️ **Do**: Publicly exposed storage buckets +::: + +#### En dashes + +Use an en dash: + +* When one of the elements in a compound adjective is an open compound (made up of two words with a space between them). + +:::{dropdown} Examples +* Windows 10–compatible products +* AI Assistant–generated content +::: + +* To indicate a range of numbers, such as inclusive values or dates. + +:::{dropdown} Examples +* The field must contain 1–3 values. +* Upgrade from v. 7.17 to v. 8.5–8.10. +::: + +#### Em dashes + +Use em dashes to indicate a break in the flow of a sentence. Don't add spaces around an em dash. + +:::{dropdown} Examples +* Consider adding exceptions—preferably with a combination of user agent and IP address conditions. +* Filter out endpoint events that you don't want to store—for example, high-volume events. +::: + +### Parentheses + +Before using parentheses, consider if you can replace them with dashes, semicolons, or other punctuation marks. If you need to include parentheses, keep the text inside them short. + +Use parentheses for abbreviations and acronyms after spelling them out. + +:::{dropdown} Examples +* Monitor the security posture of your cloud assets using the Cloud Security Posture Management (CSPM) feature. +* Expand a risk level group (for example, **High**) or an asset criticality group (for example, **high_impact**). +::: + +### Semicolons + +In general, try to simplify complex sentences to avoid using semicolons. + +Where necessary, use a semicolon to join two closely related independent clauses where a period or a comma is not as effective. + +:::{dropdown} Examples +* The endpoint is idempotent; therefore, it can safely be used to poll a given migration and, upon completion, finalize it. +* Multiple consecutive dashes in the value must be escaped; single dashes do not need to be escaped. +::: + +## Spelling + +We use [American English](#american-english) unless referring to a product, feature, API, or UI element that uses a different flavor of English, like British English. + +:::::{note} +You might notice variations in our older docs. In the past, we used all variations of English freely throughout our docs. Now, we strive for consistency to reduce uncertainty among readers and contributors. +::::: + +Outside of technical writing, Elastic has used variations of English in product, feature, and API names. Always use the spelling as it appears in the product when writing documentation. + +Similarly, if you are referencing a non-Elastic product that uses a different flavor of English, including in the UI text, use the spelling as it appears in the product. + +For example, in the [CI/CD observability guide](https://www.elastic.co/guide/en/observability/current/ci-cd-observability.html), we use the word "Visualisation" because that's how it appears in the Jenkins UI. Typically we would use the American spelling, "Visualization", instead. + +### American English + +American English is a version of the English language used in the United States. It's sometimes called United States English or U.S. English. + +Certain words are spelled differently in American English and British English. You'll find some of these key spelling differences in the following sections. + +#### Verbs that end with `-ize` or `-yze` + +In American English, verbs that end with `-ize` usually end with `-ise` in British English. Similarly, verbs that end with `-yze` in American English usually end with `-yse` in British English. + +| American English | British English | +| ------------- |:-------------:| +| organize | organise | +| authorize | authorise | +| analyze | analyse | + +#### Nouns that end with `-or` + +In American English, nouns that end with `-or` usually end with `-our` in British English. + +| American English | British English | +| ------------- |:-------------:| +| flavor | flavour | +| color | colour | +| behavior | behaviour | + +#### Nouns that end with `-ense` + +In American English, nouns that end with `-ense` usually end with `-ence` in British English. + +| American English | British English | +| ------------- |:-------------:| +| license | licence | +| defense | defence | +| pretense | pretence | + +#### Nouns that end with `-og` + +In American English, nouns that end with `-og` usually end with `-ogue` in British English. + +| American English | British English | +| ------------- |:-------------:| +| dialog | dialogue | +| catalog | catalogue | +| epilog | epilogue | + +## Capitalization + +Follow the standard capitalization rules for American English. In general, use sentence-style capitalization and follow these rules: + +* Capitalize the first word of a sentence, heading, title, or standalone phrase. +* Capitalize proper nouns and product names. +* Use lowercase for everything else. +* Match the capitalization as it appears in the UI. + +❌ Don't capitalize the spelled-out form of an acronym unless it's a proper noun or is conventionally capitalized. + +:::{dropdown} Examples +❌ **Don't**: This tab shows anomalies discovered by Machine Learning (ML) jobs. + +✔️ **Do**: This tab shows anomalies discovered by machine learning (ML) jobs. +::: + +❌ Don't capitalize API names. + +:::{dropdown} Examples +❌ **Don't**: The Bulk API makes it possible to perform many index/delete operations in a single API call. + +✔️ **Do**: The bulk API makes it possible to perform many index/delete operations in a single API call. +::: + +## Abbreviations and acronyms + +In general, spell out abbreviations when a term is unlikely to be familiar to the audience, or may be familiar only to a specific group of readers. Spell them out the first time you use them in body text—avoid using them in titles. Use the abbreviation rather than the full term for later mentions on the same page. + +### Abbreviations in titles + +Avoid using an abbreviation for the first time in a title or heading, unless you need to match the UI, for example. If the first use of the abbreviation is in a title or heading, introduce the abbreviation (in parentheses, following the spelled-out term) in the following body text. + +:::{dropdown} Examples +❌ **Don't**: ECS field reference + +✔️ **Do**: Elastic Common Schema field reference + +✔️ **Do**: Create an ES|QL rule (OK to use abbreviation since this is how the rule type appears in the UI) +::: + +### Capitalization of abbreviations + +Capitalize the spelled-out version of the abbreviation only if it's a proper noun or is conventionally capitalized. That is, don't capitalize it only because the abbreviation includes capital letters. + +:::{dropdown} Examples +❌ **Don't**: This setting determines whether Cross-Cluster Search (CCS) privilege warnings are displayed. + +✔️ **Do**: This setting determines whether cross-cluster search (CCS) privilege warnings are displayed. +::: + +### Making abbreviations plural + +When making them plural, treat abbreviations as regular words. Do not use an apostrophe before the `-s` suffix. + +If the abbreviation ends in `-s`, `-sh`, `-ch`, or `-x`, then add `-es`. + +:::{dropdown} Examples +❌ **Don't**: API's, SDK's, OS'es + +✔️ **Do**: APIs, SDKs, OSes +::: + +### Using the right article + +The article (*a* or *an*) you use in front of an abbreviation depends on how the abbreviation is pronounced, not how it's spelled. + +:::{dropdown} Examples +❌ **Don't**: a HTML file, a SQL database + +✔️ **Do**: an HTML file, an SQL database +::: + +### Latin abbreviations + +Avoid Latin abbreviations for common English phrases, unless space is limited. + +:::{dropdown} Examples +❌ **Don't**: e.g. + +✔️ **Do**: for example +::: + +## Glossary + +For a list of terms and abbreviations commonly used in our docs, refer to the [Glossary](/reference/glossary/index.md). \ No newline at end of file diff --git a/contribute-docs/style-guide/images/metatitleexample.png b/contribute-docs/style-guide/images/metatitleexample.png new file mode 100644 index 0000000000..f29847f176 Binary files /dev/null and b/contribute-docs/style-guide/images/metatitleexample.png differ diff --git a/contribute-docs/style-guide/images/onesentence.png b/contribute-docs/style-guide/images/onesentence.png new file mode 100644 index 0000000000..ff25a55c9a Binary files /dev/null and b/contribute-docs/style-guide/images/onesentence.png differ diff --git a/contribute-docs/style-guide/images/secrets-exposure.png b/contribute-docs/style-guide/images/secrets-exposure.png new file mode 100644 index 0000000000..2d12e6029f Binary files /dev/null and b/contribute-docs/style-guide/images/secrets-exposure.png differ diff --git a/contribute-docs/style-guide/images/tones.png b/contribute-docs/style-guide/images/tones.png new file mode 100644 index 0000000000..1bbbbc0c5c Binary files /dev/null and b/contribute-docs/style-guide/images/tones.png differ diff --git a/contribute-docs/style-guide/index.md b/contribute-docs/style-guide/index.md new file mode 100644 index 0000000000..95fb383367 --- /dev/null +++ b/contribute-docs/style-guide/index.md @@ -0,0 +1,21 @@ +--- +navigation_title: Style guide +--- + +# Technical writing style guide + +In this style guide, you can find editorial guidelines for writing clear, consistent documentation that reflects Elastic's friendly tone and our commitment to editorial quality. + +[**Voice and tone**](./voice-tone.md): Guidelines for maintaining a consistent voice and tone across Elastic documentation. + +[**Accessibility and inclusivity**](./accessibility.md): Guidelines for writing accessible and inclusive content. + +[**Grammar and spelling**](./grammar-spelling.md): Guidelines for using correct grammar and spelling in your writing. + +[**Formatting**](./formatting.md): Guidelines for using consistent formatting across Elastic documentation. + +[**Writing for and about the UI**](./ui-writing.md): Guidelines for writing about the user interfaces of Elastic products. + +[**SEO**](./seo.md): Guidelines for optimizing documentation for search engines, including best practices for keywords, metadata, and discoverability. + +[**Word choice**](./word-choice.md): Guidelines for choosing the right words in your documentation. \ No newline at end of file diff --git a/contribute-docs/style-guide/seo.md b/contribute-docs/style-guide/seo.md new file mode 100644 index 0000000000..463cfb3af6 --- /dev/null +++ b/contribute-docs/style-guide/seo.md @@ -0,0 +1,463 @@ +# SEO guidelines + +Learn how to structure content for search visibility, craft clear and user-focused copy, and apply techniques that improve discoverability and usability. To deliver value to users, search engines and AI-powered tools—including large language models (LLMs), use the SEO guidelines to ensure your documentation is easy to find, understand, and maintain. + +As AI-powered assistants and LLMs become more common, documentation is increasingly consumed by both humans and AI tools. Following these best practices ensures your content is discoverable, understandable, and actionable—not just for search engines and users, but also for AI-driven platforms that rely on clear structure and context to provide accurate answers and guidance. + +Use these guidelines to ensure your documentation is easy to find, understand, and maintain—delivering value to users and search engines alike. + +## Headings + +Headings provide a clear structure to your documentation, making it easier to scan and understand. For SEO, headings (H1, H2, H3, and so on) signal the hierarchy and main topics of your content, helping search engines, LLMs (Large Language Models) determine the relevance of your page to specific queries. For users, well-structured headings improve readability, accessibility, and navigation, especially for long or complex pages. + +Use headings in order, maintaining [W3C standards](https://www.w3.org/standards/). Accurately reflect the content that follows each heading. Avoid vague headings like "Introduction" or "Overview", and use specific headings like "Introduction to using Elasticsearch". Make heading text unique, especially for headings higher in the hierarchy. + +### H1: Primary page title + +The H1 is the main title of the page and should clearly state the primary topic or purpose. Search engines give significant weight to the H1. There should be only one H1 per page, and each H1 should be unique. When headings are not unique, search engines struggle to understand the differences between thematically related pages. + +Best practices: + +* Include the main topic. +* Be concise and descriptive. +* Reflect what the user will learn or accomplish. +* Be specific. Add any modifiers that make clear what the purpose of the page is. +* H1s should *always* be unique. +* Incorporate any applicable primary keywords. + +:::{dropdown} Examples + +✅Configure data views in Kibana + +❌Data views + +✅Elasticsearch documentation + +❌Elasticsearch +::: + +⚠️**Note:** The primary H1 header tag, sometimes called the page title, is what is used to populate the meta title tag, which appears on the search engines results page and impacts the Click-Through Rate (CTR). + +:::{dropdown} Examples +![Screenshot of a documentation page showing the meta title field in a content management system. The meta title field is populated with Elasticsearch Documentation. The interface includes form fields and labels in a clean, minimal layout. The tone is neutral and instructional, focusing on how the meta title is set for a documentation page.](./images/metatitleexample.png) + +The meta title, and in turn, the page title, is very broad. A more descriptive title could be "Data ingestion with Elasticsearch". +::: + +Best practices: + +* The meta title should be concise, descriptive, and include the main keyword or topic of the page. +* It's important that the H1 accurately reflects the page's content and purpose, as this will be shown in the search results. +* Avoid duplicating meta titles across different pages. Each should be unique. +* Keep the H1 to a recommended length of 50–60 characters, and make sure the most important information is at the beginning. +* The meta title is not directly visible to users on the page itself, but it's critical for search visibility and user engagement in search results. + +### H2: Secondary headings + +H2s break the content into logical sections, outlining key steps, concepts, or features. H2s help search engines understand subtopics and improve page scannability. Given the volume of documentation content, and the similarity between certain topics, try to make secondary headings unique. + +Best practices: + +* Use H2s for major sections or steps. +* Incorporate secondary keywords where relevant. +* H2s are descriptive so users can quickly find the information they need. + +:::{dropdown} Examples + +✅Configure output settings + +❌Settings + +✅Deploy Filebeat to Kubernetes + +❌Deploy +::: + +### Subheadings + +H3 and greater subheadings further divide section content into more specific topics or steps. These headings help organize detailed information and can target long-tail keywords. + +Best practices: + +* Use H3s and great subheadings for sub-steps, options, or detailed explanations within an H2 section. +* Keep them short and relevant. +* Maintain logical hierarchy and don't skip heading levels. + +:::{dropdown} Examples + +H2: Troubleshoot common issues + +H3: Resolve mapping conflicts +::: + +## Introductory paragraph + +The introductory paragraph is the first section users and search engines encounter after the H1 page title. A well-crafted introduction sets clear expectations, provides essential context, and helps both readers and search engines quickly understand the page purpose. For SEO, it's an opportunity to naturally include primary keywords and related terms, improving the page relevance for targeted queries. Sticking to any context that will help ground the visitor in the content they are about to ingest is a perfect introductory paragraph. + +Best practices: + +* Be clear and concise + * Summarize what the page covers in 1–3 sentences. Avoid unnecessary background or filler. +* State the purpose + * Clearly explain what users will learn or accomplish by reading the page. +* Include keywords + * Use primary and secondary keywords naturally within the first 1–2 sentences to reinforce relevance. +* Address the audience needs + * Reflect the user's intent, such as the problem they are trying to solve or what task are they performing. +* Avoid jargon + * Use plain language, or briefly define technical terms if needed. +* Keep it actionable + * If the page is a how-to or guide, indicate the action or outcome. + +:::{note} +If the description is missing in the frontmatter, the first sentences of the page are used in the meta description tag, up to the first 150-160 characters. This tag appears on the search engines results page and impacts CTR. It is not directly user-facing otherwise. +::: + +When a page starts with a note, image, table, or other component, the meta description is *not* impacted by the component content. Only the first paragraph content nested within the first lines of the opening paragraph tags `\`) impact the meta description. + +:::{dropdown} Examples +The following example is a page with one sentence and no introductory paragraph: + +![Screenshot of a documentation page displaying only a single sentence without an introductory paragraph. The page shows a heading at the top, followed by the sentence: Pulse Connect Secure integration enables you to collect, monitor, and analyze VPN and remote access logs from Pulse Connect Secure appliances in Elastic. The layout is minimal and lacks additional context or descriptive content, creating a sparse and utilitarian tone.](./images/onesentence.png) + +If the page had more content, which is required, a good introductory paragraph within the context of this example could be something like "The Pulse Connect Secure integration enables you to collect, monitor, and analyze VPN and remote access logs from Pulse Connect Secure appliances in Elastic. Use this integration to gain visibility into user activity, detect security events, and streamline compliance reporting within Kibana. Compatible with Elastic Stack version 8.13.0 and higher, this integration supports both Security and Observability use cases". + +In turn, the meta description would be more descriptive, for example, "The Pulse Connect Secure integration enables you to collect, monitor, and analyze VPN and remote access logs from Pulse Connect Secure appliances in Elastic". + +The ideal introduction varies by content type. For example: + +* Overview + + Heartbeat is an Elastic Stack monitoring tool that enables you to track the availability and response time of services across your infrastructure. This overview explains how Heartbeat works, its key features, and how it integrates with other Elastic solutions to provide real-time uptime monitoring and alerting. Use Heartbeat to proactively detect outages, measure service performance, and ensure your systems remain reliable. + +* How-to + + Learn how to configure index patterns in Kibana to manage and visualize your Elasticsearch data efficiently. This guide walks you through each step, from creating a new pattern to troubleshooting common issues. + +* Troubleshooting + + If you're experiencing issues with index patterns in Kibana, this page provides solutions to common problems and tips for resolving errors quickly. +::: + +## Body copy + +The body copy is where you deliver the main content of your documentation page. Well-structured, clear, and concise body copy helps users accomplish their goals and enables search engines to understand the depth and relevance of your content. For technical documentation, body copy should be easy to scan, actionable, and accurate. + +Best practices: + +* Establish authority and credibility by relaying expertise + + * Using accurate technical terms demonstrates expertise and familiarity with the subject. + * Define technical terms on first use, especially if your audience may include newcomers. + * Proper terminology reassures users that the documentation is trustworthy and written by knowledgeable authors. + * Technical terminology helps attract and serve users who are already familiar with your field or searching for in-depth information. + +* Write clearly and concisely + + * Use plain language and define technical terms on first use. + * Keep sentences and paragraphs short for readability. + * Use active voice and direct instructions. + * Avoid overusing jargon—balance technical accuracy with clarity to ensure content remains accessible. + +* Thoughtfully use relevant keywords + + * Incorporate keywords that match the search intent of your target audience and the topic of the page. + * Place keywords naturally throughout the content—especially in headings, the first paragraph, and where they fit contextually. + * Include related terms and synonyms to improve semantic relevance. + +* Organize with headings and subheadings + + * Break content into logical sections using descriptive headings (H2, H3, and so on). + * Headings help users scan for relevant information and assist search engines in understanding content hierarchy. + * Each heading should accurately reflect the content that follows. + +* Ensure content quality, originality, and uniqueness + + * Avoid thin content—ensure each page provides substantial, unique value to the reader. + * Do not duplicate content from other pages or sources; always tailor information for the specific context and audience. + * Regularly review and update content to keep it accurate and relevant. + +* Make content scannable + + * Use bullet points, numbered lists, and callouts for important information. + * Highlight warnings, tips, or best practices using clear formatting. + +* Provide examples and visuals + + * Include code snippets, sample commands, or screenshots to illustrate concepts. + * Reference visuals in the text, but ensure all key information is also available in text for accessibility. + +* Leverage structured data, where applicable + + * Use structured data (for example, [schema.org](https://schema.org/) markup) to add semantic meaning. + Structured data can help search engines display your documentation in rich results, such as FAQs or How-To snippets. + Check with the documentation team for existing capabilities or implementation guidance. + +### Content length + +The ideal length for a body copy should not be focused on word count, but instead on whether the content is enough to be satisfying to a user and accomplish its goal. + +Paragraph length is also important. Readers on the Internet are conditioned to skim, looking for emphasized words in short paragraphs. Using highlighted, pulled-out blockquote boxes, asides, call-out sections, section dividers, and other features help liven up a page. + +These visual breaks help make sure a user's attention span isn't broken. They should also not be overused, and their frequency will depend upon the relationship to the topic. + +Best practices: + +* Focus on user needs, not word count + + * The ideal length for a documentation page is determined by how well it answers the user's question or helps them accomplish their task. + * Avoid padding content to meet arbitrary word counts; instead, ensure the page is comprehensive, accurate, and directly relevant. + * If a topic is too broad, consider breaking it into multiple focused pages for easier navigation and better SEO. + +* Keep paragraphs clear and scannable + + * Online readers tend to skim rather than read every word. Ensure that content is easy to digest. + * Start paragraphs with key information and use plain language for clarity. + * Use formatting tools (bold, italics, code formatting) to highlight important terms or actions. + +### Lists + +Lists are powerful tools for organizing information in a clear, scannable format. Lists help make your content easier to read and scan, they can increase user engagement and retention, improve your content's structure and layout, and much more. + +Best practices: + +* Choose the right list type + + * Use bulleted lists for unordered items, features, or options. + * Use numbered lists for sequential steps, processes, or instructions. + +* Keep items concise and parallel + + * Write list items as short, clear phrases or sentences. + * Avoid using too many or too few list items. + * Avoid nesting lists within lists unless necessary. + * Use parallel structure (start each item with the same part of speech). + +* Introduce lists clearly + + * Use a lead-in sentence or phrase to explain what the list covers. + +* Use lists to improve scannability + + * Break up long paragraphs with lists to make content easier to scan. + * Limit lists to 5–7 items when possible; split longer lists into logical groups. + +* Naturally incorporate keywords + + * Where appropriate, use relevant keywords in list items to reinforce page relevance. + +* Maintain consistency + + * Use consistent punctuation and capitalization for all list items. + * Avoid mixing full sentences and fragments within the same list. + +* Accessibility considerations + + * Use semantic HTML (`