SpeechTilesAndamento Docs
Get started
Docs›Sdk›Stmediarunner›Publishing Spec
Guide

SpeechTiles Developer Documentation — Common Publishing Specification

This specification aligns the SDK documentation and JSON configuration documentation into one browser-based SpeechTiles developer experience. The source format may differ (.md for SDK narrative/symbol pages and structured YAML for configuration references), but the published page model is shared.

Documentation hierarchy

SDKs

Configuration

  • Conversation
  • Prompt Modules
  • Resource Formats

Guides and examples may link across these boundaries whenever the developer task spans both the Swift API and configuration.

Common page anatomy

Published reference pages should use the following order when the sections apply:

  1. Title
  2. Summary — one or two sentences answering what the symbol/property is for.
  3. Declaration / JSON form
  4. Overview — behavior and intended use.
  5. Parameters / Properties
  6. Defaults and constraints
  7. Behavior and precedence
  8. Events / results — for executable SDK operations.
  9. Examples
  10. Developer notes — only for details that materially help correct use.
  11. See Also

A page should not display empty sections.

SDK symbol pages

Swift symbols use their exact public declaration. Parameter and property descriptions should explain semantics, not merely restate Swift types. For asynchronous operations, the page must distinguish the immediate return value from later event-driven execution.

Where a method depends on component initialization or state, state the prerequisite near the top of the page.

Configuration pages

Configuration pages are generated from the structured YAML reference source. The published page should expose the same visual concepts used by SDK pages: summary, type, required/optional state, default, allowed values, runtime-field support, examples, notes, and related topics.

The browser should describe these pages as Configuration Reference, not merely "JSON Reference Guide." Individual pages may identify their serialized format as JSON.

Cross-reference convention

Cross-reference concepts, not storage formats. Examples:

  • STAudioPlayParams → Prompt Module audio playback parameters when the concepts overlap.
  • STConversationRunner → Conversation Definition.
  • Conversation speechRecognition → SDK speech-recognition guide/types.
  • Prompt Module fallback behavior → Audio Resource-to-Text Map.

The user should be able to move between SDK and Configuration documentation without returning to separate reference-guide landing pages.

Terminology

Use the current public names consistently:

  • STMediaRunner
  • STConversationRunner
  • Conversation
  • Prompt Module
  • Configuration Reference
  • SDK Reference

Historical names such as STVoiceFlow should not appear in newly published documentation except in explicit migration material.

Style

  • Lead with what a developer needs to know.
  • Preserve specialized capabilities; explain why they exist.
  • Prefer precise statements over promotional language inside reference pages.
  • Use examples to illuminate behavior, not to duplicate declarations.
  • Do not expose internal implementation types or internal class names.
  • Do not invent behavior that is not established by the current public source or validated runtime semantics.