From 5aad97651dba2fd0049f1599a78aa84d39403526 Mon Sep 17 00:00:00 2001
From: Joe McElroy <joseph.mcelroy@elastic.co>
Date: Fri, 18 Oct 2024 19:03:51 +0100
Subject: [PATCH] [Onboarding] Better onboarding copy (#196895)

## Summary

Improved onboarding copy

<img width="1433" alt="image"
src="https://github.com/user-attachments/assets/b25b7677-8acc-4875-b775-5276956ba69b">

---------

Co-authored-by: Michael DeFazio <michael.defazio@elastic.co>
Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com>
---
 .../public/code_examples/constants.ts         | 27 ++++++++++++++++---
 .../public/code_examples/create_index.ts      | 14 ++++++++++
 .../public/code_examples/ingest_data.ts       | 18 ++++++++-----
 .../add_documents_code_example.tsx            | 26 ++++++++++--------
 .../public/components/shared/code_sample.tsx  | 27 +++++++++++++++----
 .../components/start/create_index_code.tsx    | 11 +++-----
 x-pack/plugins/search_indices/public/types.ts | 11 +++++---
 7 files changed, 99 insertions(+), 35 deletions(-)

diff --git a/x-pack/plugins/search_indices/public/code_examples/constants.ts b/x-pack/plugins/search_indices/public/code_examples/constants.ts
index 31850ce7fbbe0..3ba23d0fae222 100644
--- a/x-pack/plugins/search_indices/public/code_examples/constants.ts
+++ b/x-pack/plugins/search_indices/public/code_examples/constants.ts
@@ -7,9 +7,30 @@
 
 import { i18n } from '@kbn/i18n';
 
-export const UPLOAD_VECTORS_TITLE = i18n.translate(
-  'xpack.searchIndices.codeExamples.ingest.denseVector.title',
+export const INSTALL_INSTRUCTIONS_TITLE = i18n.translate(
+  'xpack.searchIndices.code.installCommand.title',
   {
-    defaultMessage: 'Upload vectors',
+    defaultMessage: 'Install Elasticsearch client',
+  }
+);
+
+export const INSTALL_INSTRUCTIONS_DESCRIPTION = i18n.translate(
+  'xpack.searchIndices.code.installCommand.title',
+  {
+    defaultMessage: 'In your terminal, install the Elasticsearch client:',
+  }
+);
+
+export const CONNECT_CREATE_VECTOR_INDEX_CMD_TITLE = i18n.translate(
+  'xpack.searchIndices.code.createIndexCommand.title',
+  {
+    defaultMessage: 'Create an index with dense vector fields',
+  }
+);
+
+export const CONNECT_CREATE_VECTOR_INDEX_CMD_DESCRIPTION = i18n.translate(
+  'xpack.searchIndices.code.createIndexCommand.description',
+  {
+    defaultMessage: 'Use the Elasticsearch client to create an index with dense vector fields',
   }
 );
diff --git a/x-pack/plugins/search_indices/public/code_examples/create_index.ts b/x-pack/plugins/search_indices/public/code_examples/create_index.ts
index 01d969df3d70d..d462c2310ab4c 100644
--- a/x-pack/plugins/search_indices/public/code_examples/create_index.ts
+++ b/x-pack/plugins/search_indices/public/code_examples/create_index.ts
@@ -6,6 +6,12 @@
  */
 
 import { CreateIndexCodeExamples } from '../types';
+import {
+  CONNECT_CREATE_VECTOR_INDEX_CMD_DESCRIPTION,
+  CONNECT_CREATE_VECTOR_INDEX_CMD_TITLE,
+  INSTALL_INSTRUCTIONS_DESCRIPTION,
+  INSTALL_INSTRUCTIONS_TITLE,
+} from './constants';
 
 import { CurlCreateIndexExamples } from './curl';
 import { JavascriptServerlessCreateIndexExamples } from './javascript';
@@ -14,6 +20,10 @@ import { ConsoleCreateIndexExamples } from './sense';
 
 export const DefaultServerlessCodeExamples: CreateIndexCodeExamples = {
   exampleType: 'search',
+  installTitle: INSTALL_INSTRUCTIONS_TITLE,
+  installDescription: INSTALL_INSTRUCTIONS_DESCRIPTION,
+  createIndexTitle: CONNECT_CREATE_VECTOR_INDEX_CMD_TITLE,
+  createIndexDescription: CONNECT_CREATE_VECTOR_INDEX_CMD_DESCRIPTION,
   sense: ConsoleCreateIndexExamples.default,
   curl: CurlCreateIndexExamples.default,
   python: PythonServerlessCreateIndexExamples.default,
@@ -22,6 +32,10 @@ export const DefaultServerlessCodeExamples: CreateIndexCodeExamples = {
 
 export const DenseVectorSeverlessCodeExamples: CreateIndexCodeExamples = {
   exampleType: 'vector',
+  installTitle: INSTALL_INSTRUCTIONS_TITLE,
+  installDescription: INSTALL_INSTRUCTIONS_DESCRIPTION,
+  createIndexTitle: CONNECT_CREATE_VECTOR_INDEX_CMD_TITLE,
+  createIndexDescription: CONNECT_CREATE_VECTOR_INDEX_CMD_DESCRIPTION,
   sense: ConsoleCreateIndexExamples.dense_vector,
   curl: CurlCreateIndexExamples.dense_vector,
   python: PythonServerlessCreateIndexExamples.dense_vector,
diff --git a/x-pack/plugins/search_indices/public/code_examples/ingest_data.ts b/x-pack/plugins/search_indices/public/code_examples/ingest_data.ts
index 885a383295338..f2eb019bda3e9 100644
--- a/x-pack/plugins/search_indices/public/code_examples/ingest_data.ts
+++ b/x-pack/plugins/search_indices/public/code_examples/ingest_data.ts
@@ -7,21 +7,27 @@
 
 import { i18n } from '@kbn/i18n';
 import { IngestDataCodeExamples } from '../types';
-import { UPLOAD_VECTORS_TITLE } from './constants';
 
 import { JSServerlessIngestVectorDataExample } from './javascript';
 import { PythonServerlessVectorsIngestDataExample } from './python';
 import { ConsoleVectorsIngestDataExample } from './sense';
 import { CurlVectorsIngestDataExample } from './curl';
+import { INSTALL_INSTRUCTIONS_TITLE, INSTALL_INSTRUCTIONS_DESCRIPTION } from './constants';
 
 export const DenseVectorServerlessCodeExamples: IngestDataCodeExamples = {
-  title: UPLOAD_VECTORS_TITLE,
-  ingestTitle: UPLOAD_VECTORS_TITLE,
-  description: i18n.translate(
-    'xpack.searchIndices.codeExamples.serverless.denseVector.description',
+  installTitle: INSTALL_INSTRUCTIONS_TITLE,
+  installDescription: INSTALL_INSTRUCTIONS_DESCRIPTION,
+  addMappingsTitle: i18n.translate(
+    'xpack.searchIndices.codeExamples.serverless.denseVector.mappingsTitle',
+    {
+      defaultMessage: 'Define field mappings',
+    }
+  ),
+  addMappingsDescription: i18n.translate(
+    'xpack.searchIndices.codeExamples.serverless.denseVector.mappingsDescription',
     {
       defaultMessage:
-        'The following example connects to your Elasticsearch endpoint and uploads vectors to the index.',
+        'This example defines two fields: a 3-dimensional dense vector field and a text field. You can add more field types by modifying the mappings in your API call, or in the mappings tab.',
     }
   ),
   defaultMapping: {
diff --git a/x-pack/plugins/search_indices/public/components/index_documents/add_documents_code_example.tsx b/x-pack/plugins/search_indices/public/components/index_documents/add_documents_code_example.tsx
index aa8fd525c8a44..20d7fa534e674 100644
--- a/x-pack/plugins/search_indices/public/components/index_documents/add_documents_code_example.tsx
+++ b/x-pack/plugins/search_indices/public/components/index_documents/add_documents_code_example.tsx
@@ -7,7 +7,7 @@
 
 import React, { useCallback, useMemo, useState } from 'react';
 import { MappingProperty } from '@elastic/elasticsearch/lib/api/types';
-import { EuiFlexGroup, EuiFlexItem, EuiPanel, EuiText } from '@elastic/eui';
+import { EuiFlexGroup, EuiFlexItem, EuiPanel } from '@elastic/eui';
 import { i18n } from '@kbn/i18n';
 import { TryInConsoleButton } from '@kbn/try-in-console';
 
@@ -112,16 +112,12 @@ export const AddDocumentsCodeExample = ({
             </EuiFlexItem>
           )}
         </EuiFlexGroup>
-        <EuiText>
-          <p>{ingestCodeExamples.description}</p>
-        </EuiText>
         {selectedCodeExamples.installCommand && (
           <EuiFlexItem>
             <CodeSample
               id="installCodeExample"
-              title={i18n.translate('xpack.searchIndices.indexDetails.installLibrary.title', {
-                defaultMessage: 'Install Elasticsearch library',
-              })}
+              title={ingestCodeExamples.installTitle}
+              description={ingestCodeExamples.installDescription}
               language="shell"
               code={selectedCodeExamples.installCommand}
               onCodeCopyClick={() => {
@@ -137,9 +133,8 @@ export const AddDocumentsCodeExample = ({
           <EuiFlexItem>
             <CodeSample
               id="addMappingsCodeExample"
-              title={i18n.translate('xpack.searchIndices.indexDetails.addMappingsCode.title', {
-                defaultMessage: 'Add mappings to your index',
-              })}
+              title={ingestCodeExamples.addMappingsTitle}
+              description={ingestCodeExamples.addMappingsDescription}
               language={Languages[selectedLanguage].codeBlockLanguage}
               code={selectedCodeExamples.updateMappingsCommand(codeParams)}
               onCodeCopyClick={() => {
@@ -154,7 +149,16 @@ export const AddDocumentsCodeExample = ({
         <EuiFlexItem>
           <CodeSample
             id="ingestDataCodeExample"
-            title={ingestCodeExamples.ingestTitle}
+            title={i18n.translate('xpack.searchIndices.indexDetails.ingestDocuments.title', {
+              defaultMessage: 'Ingest documents',
+            })}
+            description={i18n.translate(
+              'xpack.searchIndices.indexDetails.ingestDocuments.description',
+              {
+                defaultMessage:
+                  'Next, use the Elasticsearch bulk API to ingest an array of documents into the index.',
+              }
+            )}
             language={Languages[selectedLanguage].codeBlockLanguage}
             code={selectedCodeExamples.ingestCommand(codeParams)}
             onCodeCopyClick={() => {
diff --git a/x-pack/plugins/search_indices/public/components/shared/code_sample.tsx b/x-pack/plugins/search_indices/public/components/shared/code_sample.tsx
index fc233e498ea10..ee35d3c884c2a 100644
--- a/x-pack/plugins/search_indices/public/components/shared/code_sample.tsx
+++ b/x-pack/plugins/search_indices/public/components/shared/code_sample.tsx
@@ -13,6 +13,7 @@ import {
   EuiFlexItem,
   EuiPanel,
   EuiSpacer,
+  EuiTitle,
   EuiText,
   EuiThemeProvider,
 } from '@elastic/eui';
@@ -20,12 +21,20 @@ import {
 export interface CodeSampleProps {
   id?: string;
   title: string;
+  description?: string;
   language: string;
   code: string;
   onCodeCopyClick?: React.MouseEventHandler<HTMLElement>;
 }
 
-export const CodeSample = ({ id, title, language, code, onCodeCopyClick }: CodeSampleProps) => {
+export const CodeSample = ({
+  id,
+  title,
+  language,
+  code,
+  onCodeCopyClick,
+  description,
+}: CodeSampleProps) => {
   const onCodeClick = React.useCallback(
     (e: React.MouseEvent<HTMLElement, MouseEvent>) => {
       if (onCodeCopyClick === undefined) return;
@@ -40,10 +49,18 @@ export const CodeSample = ({ id, title, language, code, onCodeCopyClick }: CodeS
 
   return (
     <EuiFlexItem id={id}>
-      <EuiText size="s">
-        <strong>{title}</strong>
-      </EuiText>
-      <EuiSpacer size="s" />
+      <EuiTitle size="xs">
+        <h3>{title}</h3>
+      </EuiTitle>
+      {description && (
+        <>
+          <EuiSpacer size="xs" />
+          <EuiText size="s" grow={false}>
+            <p>{description}</p>
+          </EuiText>
+        </>
+      )}
+      <EuiSpacer size="m" />
       <EuiThemeProvider colorMode="dark">
         <EuiPanel color="subdued" paddingSize="none" hasShadow={false}>
           <div onClick={onCodeClick}>
diff --git a/x-pack/plugins/search_indices/public/components/start/create_index_code.tsx b/x-pack/plugins/search_indices/public/components/start/create_index_code.tsx
index ed473b1a63012..eda63a5f95594 100644
--- a/x-pack/plugins/search_indices/public/components/start/create_index_code.tsx
+++ b/x-pack/plugins/search_indices/public/components/start/create_index_code.tsx
@@ -6,7 +6,6 @@
  */
 import React, { useCallback, useMemo } from 'react';
 import { EuiFlexGroup, EuiFlexItem } from '@elastic/eui';
-import { i18n } from '@kbn/i18n';
 import { TryInConsoleButton } from '@kbn/try-in-console';
 
 import { useSearchApiKey } from '@kbn/search-api-keys-components';
@@ -99,9 +98,8 @@ export const CreateIndexCodeView = ({
       </EuiFlexGroup>
       {selectedCodeExample.installCommand && (
         <CodeSample
-          title={i18n.translate('xpack.searchIndices.startPage.codeView.installCommand.title', {
-            defaultMessage: 'Install Elasticsearch serverless client',
-          })}
+          title={selectedCodeExamples.installTitle}
+          description={selectedCodeExamples.installDescription}
           language="shell"
           code={selectedCodeExample.installCommand}
           onCodeCopyClick={() => {
@@ -114,9 +112,8 @@ export const CreateIndexCodeView = ({
       )}
       <CodeSample
         id="createIndex"
-        title={i18n.translate('xpack.searchIndices.startPage.codeView.createIndex.title', {
-          defaultMessage: 'Connect and create an index',
-        })}
+        title={selectedCodeExamples.createIndexTitle}
+        description={selectedCodeExamples.createIndexDescription}
         language={Languages[selectedLanguage].codeBlockLanguage}
         code={selectedCodeExample.createIndex(codeParams)}
         onCodeCopyClick={() => {
diff --git a/x-pack/plugins/search_indices/public/types.ts b/x-pack/plugins/search_indices/public/types.ts
index 51c05687f9dc6..8a42bf9950f21 100644
--- a/x-pack/plugins/search_indices/public/types.ts
+++ b/x-pack/plugins/search_indices/public/types.ts
@@ -88,6 +88,10 @@ export interface CreateIndexCodeDefinition {
 
 export interface CreateIndexCodeExamples {
   exampleType: string;
+  installTitle: string;
+  installDescription: string;
+  createIndexTitle: string;
+  createIndexDescription: string;
   sense: CreateIndexCodeDefinition;
   curl: CreateIndexCodeDefinition;
   python: CreateIndexCodeDefinition;
@@ -109,9 +113,10 @@ export interface IngestDataCodeDefinition {
 }
 
 export interface IngestDataCodeExamples {
-  title: string;
-  ingestTitle: string;
-  description: string;
+  addMappingsTitle: string;
+  addMappingsDescription: string;
+  installTitle: string;
+  installDescription: string;
   defaultMapping: Record<string, MappingProperty>;
   sense: IngestDataCodeDefinition;
   curl: IngestDataCodeDefinition;