Merge pull request #382 from eric-urban/eur/speech-refresh

refresh speech docs

Author: Jill Grant

articles/ai-services/speech-service/how-to-configure-openssl-linux.md

@@ -1,15 +1,17 @@
 ---
 title: How to configure OpenSSL for Linux
 titleSuffix: Azure AI services
-description: Learn how to configure OpenSSL for Linux.
-author: jhakulin
+description: In this guide, you learn how to configure OpenSSL for Linux with the Azure AI Speech SDK.
+author: eric-urban
+ms.author: eur
 manager: nitinme
 ms.service: azure-ai-speech
 ms.custom: devx-track-extended-java, devx-track-go, devx-track-python, linux-related-content
 ms.topic: how-to
-ms.date: 1/18/2024
-ms.author: jhakulin
+ms.date: 9/19/2024
+ms.reviewer: jhakulin
 zone_pivot_groups: programming-languages-set-three
+#Customer intent: As a developer, I want to learn how to configure OpenSSL for Linux so that I can use the Speech SDK on my Linux system.
 ---
 
 # Configure OpenSSL for Linux
@@ -19,7 +21,7 @@ With the Speech SDK, [OpenSSL](https://www.openssl.org) is dynamically configure
 > [!NOTE]
 > This article is only applicable where the Speech SDK is [supported on Linux](speech-sdk.md#supported-languages).
 
-To ensure connectivity, verify that OpenSSL certificates have been installed in your system. Run a command:
+To ensure connectivity, verify that OpenSSL certificates are installed in your system. Run a command:
 ```bash
 openssl version -d
 ```
@@ -29,7 +31,7 @@ The output on Ubuntu/Debian based systems should be:
 OPENSSLDIR: "/usr/lib/ssl"
 ```
 
-Check whether there's a `certs` subdirectory under OPENSSLDIR. In the example above, it would be `/usr/lib/ssl/certs`.
+Check whether there's a `certs` subdirectory under OPENSSLDIR. In the previous example, it would be `/usr/lib/ssl/certs`.
 
 * If the `/usr/lib/ssl/certs` exists, and if it contains many individual certificate files (with `.crt` or `.pem` extension), there's no need for further actions.
 
@@ -52,9 +54,9 @@ export SSL_CERT_FILE=/etc/pki/tls/certs/ca-bundle.crt
 
 ## Certificate revocation checks
 
-When the Speech SDK connects to the Speech service, it checks the Transport Layer Security (TLS/SSL) certificate. The Speech SDK verifies that the certificate reported by the remote endpoint is trusted and hasn't been revoked. This verification provides a layer of protection against attacks involving spoofing and other related vectors. The check is accomplished by retrieving a certificate revocation list (CRL) from a certificate authority (CA) used by Azure. A list of Azure CA download locations for updated TLS CRLs can be found in [this document](/azure/security/fundamentals/tls-certificate-changes).
+When the Speech SDK connects to the Speech service, it checks the Transport Layer Security (TLS/SSL) certificate. The Speech SDK verifies that the certificate reported by the remote endpoint is trusted and isn't revoked. This verification provides a layer of protection against attacks involving spoofing and other related vectors. The check is accomplished by retrieving a certificate revocation list (CRL) from a certificate authority (CA) used by Azure. A list of Azure CA download locations for updated TLS CRLs can be found in [this document](/azure/security/fundamentals/tls-certificate-changes).
 
-If a destination posing as the Speech service reports a certificate that's been revoked in a retrieved CRL, the SDK terminates the connection and reports an error via a `Canceled` event. The authenticity of a reported certificate can't be checked without an updated CRL. Therefore, the Speech SDK also treats a failure to download a CRL from an Azure CA location as an error.
+If a destination posing as the Speech service reports a revoked certificate in a retrieved CRL, the SDK terminates the connection and reports an error via a `Canceled` event. The authenticity of a reported certificate can't be checked without an updated CRL. Therefore, the Speech SDK also treats a failure to download a CRL from an Azure CA location as an error.
 
 > [!WARNING]
 > If your solution uses proxy or firewall it should be configured to allow access to all certificate revocation list URLs used by Azure. Note that many of these URLs are outside of `microsoft.com` domain, so allowing access to `*.microsoft.com` is not enough. See [this document](/azure/security/fundamentals/tls-certificate-changes) for details. In exceptional cases you may ignore CRL failures (see [the correspondent section](#bypassing-or-ignoring-crl-failures)), but such configuration is strongly not recommended, especially for production scenarios.
@@ -63,7 +65,7 @@ If a destination posing as the Speech service reports a certificate that's been
 
 One cause of CRL-related failures is the use of large CRL files. This class of error is typically only applicable to special environments with extended CA chains. Standard public endpoints shouldn't encounter this class of issue.
 
-The default maximum CRL size used by the Speech SDK (10 MB) can be adjusted per config object. The property key for this adjustment is `CONFIG_MAX_CRL_SIZE_KB` and the value, specified as a string, is by default "10000" (10 MB). For example, when creating a `SpeechRecognizer` object (that manages a connection to the Speech service), you can set this property in its `SpeechConfig`. In the snippet below, the configuration is adjusted to permit a CRL file size up to 15 MB.
+The default maximum CRL size used by the Speech SDK (10 MB) can be adjusted per config object. The property key for this adjustment is `CONFIG_MAX_CRL_SIZE_KB` and the value, specified as a string, is by default "10000" (10 MB). For example, when creating a `SpeechRecognizer` object (that manages a connection to the Speech service), you can set this property in its `SpeechConfig`. In the following code snippet, the configuration is adjusted to permit a CRL file size up to 15 MB.
 
 ::: zone pivot="programming-language-csharp"
 
@@ -155,7 +157,7 @@ speechConfig.properties.SetPropertyByString("OPENSSL_CONTINUE_ON_CRL_DOWNLOAD_FA
 
 ::: zone-end
 
-To turn off certificate revocation checks, set the property `"OPENSSL_DISABLE_CRL_CHECK"` to `"true"`. Then, while connecting to the Speech service, there will be no attempt to check or download a CRL and no automatic verification of a reported TLS/SSL certificate.
+To turn off certificate revocation checks, set the property `"OPENSSL_DISABLE_CRL_CHECK"` to `"true"`. Then, while connecting to the Speech service, there's no attempt to check or download a CRL and no automatic verification of a reported TLS/SSL certificate.
 
 ::: zone pivot="programming-language-csharp"
 
@@ -203,7 +205,7 @@ By default, the Speech SDK will cache a successfully downloaded CRL on disk to i
 
 Some Linux distributions don't have a `TMP` or `TMPDIR` environment variable defined, so the Speech SDK doesn't cache downloaded CRLs. Without `TMP` or `TMPDIR` environment variable defined, the Speech SDK downloads a new CRL for each connection. To improve initial connection performance in this situation, you can [create a `TMPDIR` environment variable and set it to the accessible path of a temporary directory.](https://help.ubuntu.com/community/EnvironmentVariables).
 
-## Next steps
+## Related content
 
 - [Speech SDK overview](speech-sdk.md)
 - [Install the Speech SDK](quickstarts/setup-platform.md)

articles/ai-services/speech-service/how-to-control-connections.md

@@ -2,15 +2,17 @@
 title: Service connectivity how-to - Speech SDK
 titleSuffix: Azure AI services
 description: Learn how to monitor for connection status and manually connect or disconnect from the Speech service.
-author: trrwilson
+author: eric-urban
+ms.author: eur
 manager: nitinme
 ms.service: azure-ai-speech
 ms.topic: how-to
-ms.date: 1/18/2024
-ms.author: travisw
+ms.date: 9/19/2024
+ms.reviewer: travisw
 zone_pivot_groups: programming-languages-set-thirteen
 ms.devlang: cpp
 ms.custom: devx-track-csharp, devx-track-extended-java
+#Customer intent: As a developer, I want to learn how to monitor and control service connections with the Speech SDK so that I can manage connections to the Speech service.
 ---
 
 # How to monitor and control service connections with the Speech SDK
@@ -96,14 +98,14 @@ connection.disconnected.addEventListener((s, connectionEventArgs) -> {
 
 `Connection` has explicit methods to start or end a connection to the Speech service. Reasons you might want to control the connection include:
 
-- Preconnecting to the Speech service to allow the first interaction to start as quickly as possible
-- Establishing connection at a specific time in your application's logic to gracefully and predictably handle initial connection failures
-- Disconnecting to clear an idle connection when you don't expect immediate reconnection but also don't want to destroy the object
+- Preconnecting to the Speech service to allow the first interaction to start as quickly as possible.
+- Establishing connection at a specific time in your application's logic to gracefully and predictably handle initial connection failures.
+- Disconnecting to clear an idle connection when you don't expect immediate reconnection but also don't want to destroy the object.
 
 Some important notes on the behavior when manually modifying connection state:
 
-- Trying to connect when already connected will do nothing. It will not generate an error. Monitor the `Connected` and `Disconnected` events if you want to know the current state of the connection.
-- A failure to connect that originates from a problem that has no involvement with the Speech service--such as attempting to do so from an invalid state--will throw or return an error as appropriate to the programming language. Failures that require network resolution--such as authentication failures--won't throw or return an error but instead generate a `Canceled` event on the top-level object the `Connection` was created from.
+- Trying to connect when already connected doesn't generate an error. Monitor the `Connected` and `Disconnected` events if you want to know the current state of the connection.
+- A failure to connect that originates from a problem that has no involvement with the Speech service--such as attempting to do so from an invalid state--results in an error as appropriate to the programming language. Failures that require network resolution--such as authentication failures--doesn't result in an error but instead generate a `Canceled` event on the top-level object the `Connection` was created from.
 - Manually disconnecting from the Speech service during an ongoing interaction results in a connection error and loss of data for that interaction. Connection errors are surfaced on the appropriate top-level object's `Canceled` event.
 
 ::: zone pivot="programming-language-csharp"

articles/ai-services/speech-service/how-to-custom-speech-continuous-integration-continuous-deployment.md

@@ -2,12 +2,13 @@
 title: CI/CD for custom speech - Speech service
 titleSuffix: Azure AI services
 description: Apply DevOps with custom speech and CI/CD workflows. Implement an existing DevOps solution for your own project.
-author: nitinme
-manager: cmayomsft
+author: eric-urban
+ms.author: eur
+manager: nitinme
 ms.service: azure-ai-speech
 ms.topic: how-to
-ms.date: 1/19/2024
-ms.author: nitinme
+ms.date: 9/19/2024
+#Customer intent: As a developer, I want to learn how to apply DevOps with custom speech and CI/CD workflows so that I can implement an existing DevOps solution for my own project.
 ---
 
 # CI/CD for custom speech
@@ -18,15 +19,15 @@ Implement automated training, testing, and release management to enable continuo
 
 [Continuous delivery](/devops/deliver/what-is-continuous-delivery) (CD) takes models from the CI process and creates an endpoint for each improved custom speech model. CD makes endpoints easily available to be integrated into solutions.
 
-Custom CI/CD solutions are possible, but for a robust, pre-built solution, use the [Speech DevOps template repository](https://github.com/Azure-Samples/Speech-Service-DevOps-Template), which executes CI/CD workflows using GitHub Actions.
+Custom CI/CD solutions are possible, but for a robust, prebuilt solution, use the [Speech DevOps template repository](https://github.com/Azure-Samples/Speech-Service-DevOps-Template), which executes CI/CD workflows using GitHub Actions.
 
 ## CI/CD workflows for custom speech
 
-The purpose of these workflows is to ensure that each custom speech model has better recognition accuracy than the previous build. If the updates to the testing and/or training data improve the accuracy, these workflows create a new custom speech endpoint.
+The purpose of these workflows is to ensure that each custom speech model has better recognition accuracy than the previous build. If the updates to the testing or training data improve the accuracy, these workflows create a new custom speech endpoint.
 
 Git servers such as GitHub and Azure DevOps can run automated workflows when specific Git events happen, such as merges or pull requests. For example, a CI workflow can be triggered when updates to testing data are pushed to the *main* branch. Different Git Servers have different tooling, but allow scripting command-line interface (CLI) commands so that they can execute on a build server.
 
-Along the way, the workflows should name and store data, tests, test files, models, and endpoints such that they can be traced back to the commit or version they came from. It's also helpful to name these assets so that it's easy to see which were created after updating testing data versus training data.
+The workflows should name and store data, tests, test files, models, and endpoints such that they can be traced back to the commit or version they came from. It's also helpful to name these assets so that it's easy to see which were created after updating testing data versus training data.
 
 ### CI workflow for testing data updates
 

articles/ai-services/speech-service/how-to-custom-speech-create-project.md

@@ -6,9 +6,10 @@ author: eric-urban
 manager: nitinme
 ms.service: azure-ai-speech
 ms.topic: how-to
-ms.date: 7/15/2024
+ms.date: 9/19/2024
 ms.author: eur
 zone_pivot_groups: speech-studio-cli-rest
+#Customer intent: As a developer, I want to learn how to create a project for custom speech so that I can train and deploy a custom model.
 ---
 
 # Create a custom speech project

articles/ai-services/speech-service/how-to-custom-speech-deploy-model.md

@@ -6,9 +6,10 @@ author: eric-urban
 manager: nitinme
 ms.service: azure-ai-speech
 ms.topic: how-to
-ms.date: 7/15/2024
+ms.date: 9/19/2024
 ms.author: eur
 zone_pivot_groups: speech-studio-cli-rest
+#Customer intent: As a developer, I want to learn how to deploy a custom speech model so that I can use it in my applications.
 ---
 
 # Deploy a custom speech model
@@ -385,7 +386,7 @@ The locations of each log file with more details are returned in the response bo
 
 Logging data is available on Microsoft-owned storage for 30 days, and then it's removed. If your own storage account is linked to the Azure AI services subscription, the logging data isn't automatically deleted.
 
-## Next steps
+## Related content
 
 - [CI/CD for custom speech](how-to-custom-speech-continuous-integration-continuous-deployment.md)
 - [Custom speech model lifecycle](how-to-custom-speech-model-and-endpoint-lifecycle.md)

articles/ai-services/speech-service/how-to-custom-speech-display-text-format.md

@@ -6,8 +6,9 @@ author: eric-urban
 manager: nitinme
 ms.service: azure-ai-speech
 ms.topic: how-to
-ms.date: 1/19/2024
+ms.date: 9/19/2024
 ms.author: eur
+#Customer intent: As a developer, I want to learn how to prepare display text format training data for custom speech so that I can customize the display text formatting pipeline for my specific scenarios.
 ---
 
 # How to prepare display text format training data for custom speech

articles/ai-services/speech-service/how-to-custom-speech-evaluate-data.md

@@ -6,11 +6,12 @@ author: eric-urban
 manager: nitinme
 ms.service: azure-ai-speech
 ms.topic: how-to
-ms.date: 7/15/2024
+ms.date: 9/19/2024
 ms.author: eur
 zone_pivot_groups: speech-studio-cli-rest
 show_latex: true
 no-loc: [$$, '\times', '\over']
+#Customer intent: As a developer, I want to test the accuracy of a custom speech model so that I can evaluate whether it meets my requirements.
 ---
 
 # Test accuracy of a custom speech model

articles/ai-services/speech-service/how-to-custom-speech-human-labeled-transcriptions.md

@@ -6,8 +6,9 @@ author: eric-urban
 manager: nitinme
 ms.service: azure-ai-speech
 ms.topic: how-to
-ms.date: 1/19/2024
+ms.date: 9/19/2024
 ms.author: eur
+#Customer intent: As a developer, I need to understand how to create human-labeled transcriptions for my audio data so that I can improve speech recognition accuracy.
 ---
 
 # How to create human-labeled transcriptions

articles/ai-services/speech-service/how-to-custom-speech-inspect-data.md

@@ -6,9 +6,10 @@ author: eric-urban
 manager: nitinme
 ms.service: azure-ai-speech
 ms.topic: how-to
-ms.date: 7/15/2024
+ms.date: 9/19/2024
 ms.author: eur
 zone_pivot_groups: speech-studio-cli-rest
+#Customer intent: As a developer, I want to test the recognition quality of a custom speech model so that I can determine if the provided recognition result is correct.
 ---
 
 # Test recognition quality of a custom speech model

articles/ai-services/speech-service/how-to-custom-speech-model-and-endpoint-lifecycle.md

@@ -2,13 +2,15 @@
 title: Model lifecycle of custom speech - Speech service
 titleSuffix: Azure AI services
 description: Custom speech provides base models for training and lets you create custom models from your data. This article describes the timelines for models and for endpoints that use these models.
-author: heikora
-manager: dongli
+author: eric-urban
+manager: nitinme
+ms.author: eur
 ms.service: azure-ai-speech
 ms.topic: how-to
-ms.date: 1/19/2024
-ms.author: heikora
+ms.date: 9/19/2024
+ms.reviewer: heikora
 zone_pivot_groups: speech-studio-cli-rest
+#Customer intent: As a developer, I want to understand the lifecycle of custom speech models and endpoints so that I can plan for the expiration of my models.
 ---
 
 # Custom speech model lifecycle