Feedback: speech-to-text-pre-recorded-audio-automatic-punctuation-and-casing

Documentation Feedback

Original URL: https://www.assemblyai.com/docs/speech-to-text/pre-recorded-audio/automatic-punctuation-and-casing
Category: speech-to-text
Generated: 05/08/2025, 4:26:01 pm

---

Claude Sonnet 4 Feedback

Generated: 05/08/2025, 4:26:00 pm

Technical Documentation Analysis: Automatic Punctuation and Casing

Overall Assessment

This documentation covers the basic functionality but has several gaps that could confuse users and create friction. The structure is clear, but it lacks depth and practical guidance.

Critical Issues to Address

1. Missing Information

Add a comprehensive introduction section:

## Overview
Automatic Punctuation and Casing intelligently formats your transcriptions by:
- Adding punctuation marks (periods, commas, question marks, exclamation points)
- Capitalizing proper nouns, sentence beginnings, and acronyms
- Converting spoken numbers to numerical form ("twenty-five" → "25")

This feature is enabled by default and works automatically without additional configuration.

Missing parameter details:

• Add a dedicated “Parameters” section explaining both punctuate and format_text in detail
• Include data types, default values, and interdependencies
• Clarify what happens when only one parameter is disabled

Add troubleshooting section:

## Troubleshooting
- **Issue**: Transcription still shows punctuation after setting `punctuate=False`
  **Solution**: Ensure both API request was successful and check response format
- **Issue**: Numbers not converting as expected
  **Solution**: This behavior varies by language - see language-specific notes below

2. Unclear Explanations

Expand the language support note:

<Note title="Language Support Details">
Automatic Punctuation and Casing is supported for all languages, but effectiveness varies:

**Fully optimized**: English, Spanish, German
**Good support**: French, Italian, Portuguese, Dutch
**Basic support**: All other supported languages

For languages with basic support, disabling these features may produce inconsistent results.
</Note>

Clarify the relationship between parameters:

## Parameter Interaction
- `punctuate=False`: Removes periods, commas, question marks, etc.
- `format_text=False`: Disables capitalization and number formatting
- **Both disabled**: Produces raw transcription text closest to spoken words
- **Recommendation**: For most use cases, disable both together or keep both enabled

3. Better Examples

Add before/after examples:

## Examples

### Default Behavior (Enabled)
**Audio**: "Hello my name is John Smith and I live at 123 Main Street"
**Output**: "Hello, my name is John Smith and I live at 123 Main Street."

### Disabled (`punctuate=False, format_text=False`)
**Audio**: "Hello my name is John Smith and I live at 123 Main Street"
**Output**: "hello my name is john smith and i live at one hundred twenty three main street"

### Mixed Content Example
**Audio**: "The CEO of NASA announced that twenty-five astronauts will launch on December 1st"

**Enabled**: "The CEO of NASA announced that 25 astronauts will launch on December 1st."
**Disabled**: "the ceo of nasa announced that twenty five astronauts will launch on december first"

Add language-specific examples:

### Language-Specific Behavior

**Spanish Example:**
- Enabled: "Hola, mi nombre es María García."
- Disabled: "hola mi nombre es maría garcía"

**German Example:**
- Enabled: "Guten Tag, ich heiße Hans Müller."
- Disabled: "guten tag ich heiße hans müller"

4. Structure Improvements

Reorganize the content flow:

# Automatic Punctuation and Casing

## Overview
[Brief introduction and benefits]

## How It Works
[Detailed explanation of the feature]

## Configuration
### Parameters
### Language Considerations

## Examples
### Basic Examples
### Language-Specific Examples

## Code Implementation
[Current tabs section]

## Best Practices
## Troubleshooting
## Related Features

5. User Pain Points

Address common questions:

## Frequently Asked Questions

**Q: Can I disable only punctuation but keep capitalization?**
A: Yes, set `punctuate=False` and `format_text=True`. However, `format_text` controls both capitalization AND number formatting.

**Q: Why are my results inconsistent when disabling these features?**
A: Results vary by language. This feature works best when disabled for English, Spanish, and German content.

**Q: Does this affect processing time or cost?**
A: No, this feature is included in standard processing with no additional time or cost.

**Q: Can I re-enable formatting after transcription?**
A: No, you must set these parameters before starting transcription. Consider keeping the default enabled settings unless you specifically need raw text.

Add performance and billing notes:

## Important Notes
- These settings cannot be changed after transcription begins
- No additional cost or processing time
- For real-time transcription, these same parameters apply
- Raw text output may require post-processing for readability

Improve code examples:

• Add error handling examples
• Show response format differences
• Include validation steps
• Add comments explaining why someone would disable these features

Add cross-references:

## Related Features
- [Language Detection](link) - Automatic language detection works with punctuation
- [Custom Vocabulary](link) - Ensure proper nouns are recognized correctly
- [Real-time Transcription](link) - These settings apply to streaming as well

Quick Wins

1. Add a comparison table showing enabled vs. disabled output
2. Include use cases for when to disable (data analysis, custom formatting pipelines)
3. Add validation examples in code samples
4. Include links to language-specific documentation
5. Add a “Next Steps” section with related features

This documentation would benefit significantly from these improvements to reduce user confusion and support tickets.

---