BETS Product Documentation Guidelines

#Purpose

BETS documentation must follow a consistent structure and style. Consistency builds familiarity, which reduces friction, encourages adoption, and prevents misunderstandings. Poor documentation leads to workarounds and hacks—customers have, in the past, modified BETS widgets in unsupported ways instead of using available configurable features. Such outcomes are costly and damaging, both for users and for product integrity.

The following guidelines define a common format and level of detail that all BETS documentation should adhere to. Our goal is to create documentation that is clear, comprehensive, and authoritative, reducing the need for support and ensuring customers can unlock full product value.

#Coarse Guidelines

A document describing a product must contain the following sections:

• Title Concise, with an optional subtitle.

• Functionality Outline A high-level overview of the product, its features, and benefits. After reading this, a user should clearly understand what the product does, who it is for, and how it adds value.

• Supported Content and Environment Exact specification of the support matrix, specifically which sports, tournaments, seasons, teams are supported by the product.

• Main Configurable Features A list of main configurable features, that illustrate the most common use cases.

• API References All relevant API calls must be documented. Each call must include all parameters and respective descriptions of related functionality. This section should serve as the technical reference point for developers.

• Examples Examples combine code with context. Each example must describe where and how it should be applied, any prerequisites, and the expected outcome. Examples should cover common use cases and integration scenarios.

#Details Per Section

#Title

• Title must be front-matters (needed by API hub)
• Must be concise and clear.
• Must be in strict title case
• May include an optional subtitle if it adds necessary context (outside front-matters).
• Should make the product immediately identifiable.
• Should avoid internal code names or acronyms unless they are user-facing.

View Example

Include Snippet Error

Could not load file '../widgets/match/Widgets.match.Scoreboard.updated.example.md'

How Not To Do It

Include Snippet Error

Could not load file 'negative_examples.md'

Include Snippet Error

Could not load file 'negative_examples.md'

#Functionality Outline (Overview)

• One to two paragraphs (preferably one).
• Must describe:
  • Main functionality and purpose.
  • Primary use cases.
  • Look and feel
• This section is a sufficient introduction for customers integrating the product.
• Do not use marketing language
• Do not duplicate information
• Keep level reasonably high, do not delve into every possible tiny feature
• At the end link to widget demo

View examples

Include Snippet Error

Could not load file '../widgets/match/Widgets.match.Scoreboard.updated.example.md'

How Not To Do It

Include Snippet Error

Could not load file 'negative_examples.md'

#Supported Content and Environment

• A clear specification of supported content
  • list limited sports, if any
  • cross reference with supported sports in widget demo
  • consult Supported Sports Confluence page
  • Do not mention supported tournaments
  • list limited seasons, if any
• specify browser/environment compatibility (include snippet from global environment specification document for all widgets)
• any sport-specific functionality must be listed as a part of this section

View example

Include Snippet Error

Could not load file '../widgets/match/Widgets.match.Scoreboard.updated.example.md'

How Not To Do It

Include Snippet Error

Could not load file 'negative_examples.md'

#Main Configurable Features

• Provide a list of major use cases
  • Illustrate them with screenshots
    • Each screenshot must include combination of properties required to produce the screenshot
  • Stick to major use cases
    • Do not list mere graphic or layout options
    • It is not a problem if a product only has one main use case, do not invent use cases to fulfill this section

View examples

Include Snippet Error

Could not load file '../widgets/match/Widgets.match.Scoreboard.updated.example.md'

How Not To Do It

Include Snippet Error

Could not load file 'negative_examples.md'

Include Snippet Error

Could not load file 'negative_examples.md'

#API Specification

• Document all API functions, including both module calls and callbacks.
• For each API function:
  • Name and describe it clearly.
  • List all parameters.
    • Required vs optional.
    • Data types.
    • Constraints (e.g., invalid characters, length limits).
    • External data requirements (with references to sources).
    • Provide semantic descriptions for each parameter.
    • If value is enum, list all values with their semantic effects, unless self explanatory
    • if value is object, specify the entire object
    • If parameter description does not comfortably fit into the table, describe the property below in a separate paragraph or table and anchor link to the description
  • Provide an example call.
  • Where possible, link to an authoritative API spec (e.g., Swagger/OpenAPI).

View examples

Include Snippet Error

Could not load file '../widgets/match/Widgets.match.Scoreboard.updated.example.md'

How Not To Do It

Include Snippet Error

Could not load file 'negative_examples.md'

#Examples

• Each example must include:
  • transformation of properties from format listed in API Specification to format used in the example
  • Realistic use cases (not trivial code snippets).
• Examples should illustrate:
  • Proper placement of code.
  • Correct parameter naming
  • Required configuration values.
• Linking to a working demo is strongly encouraged.

View examples

Include Snippet Error

Could not load file '../widgets/match/Widgets.match.Scoreboard.updated.example.md'

How Not To Do It

Include Snippet Error

Could not load file 'negative_examples.md'