Improved custom vocabulary description to explain phoneme-based method

chapters/live-stt/features/custom-vocabulary.mdx

@@ -4,9 +4,11 @@ description: "Boost recognition of domain-specific words and phrases in real tim
 ---
 
 import CustomVocabularyParams from '/snippets/custom-vocabulary-params.mdx'
+import CustomVocabularyDescription from '/snippets/custom-vocabulary-description.mdx'
 
-To enhance the precision of words you know will recur often in your transcription, use the `custom_vocabulary` feature.
+<CustomVocabularyDescription />
 
+## Example configuration
 ```json
 {
   "realtime_processing": {

chapters/pre-recorded-stt/features/custom-vocabulary.mdx

@@ -4,9 +4,11 @@ description: "Improve recognition of expected vocabulary in your files"
 ---
 
 import CustomVocabularyParams from '/snippets/custom-vocabulary-params.mdx'
+import CustomVocabularyDescription from '/snippets/custom-vocabulary-description.mdx'
 
-To enhance the precision of transcription, especially for recurring words or phrases, use `custom_vocabulary`.
+<CustomVocabularyDescription />
 
+## Example configuration
 ```json request data
 {
   "audio_url": "YOUR_AUDIO_URL",

snippets/custom-vocabulary-description.mdx

@@ -0,0 +1,9 @@
+The custom vocabulary feature allows you to process your transcription results by replacing specific words with terms that better fit your domain. This is especially useful for company names, product names, technical terms, or uncommon words that are often mis-transcribed by speech to text models.
+
+### How it works
+
+Custom vocabulary operates at a **word level** and is based on **phoneme similarity**.
+
+Once the transcription is generated, Gladia compares the phonemes of the transcribed words with the phonemes of the words you provided in your custom vocabulary. If the similarity score is above a defined similarity, the word in the transcription is replaced.
+
+Alongside the word value, the pronunciations list allows you to define alternative ways a word can be pronounced. This helps cover a wider phoneme range without having to increase the similarity threshold, which could otherwise lead to false positives. It is especially useful for words with multiple common pronunciations, foreign words, or variations caused by accents.