[Help wanted] Create glossary entries for important Dart terms

[parlough]

Overview

We now have expanded support for a shared glossary on the Dart site. Currently definitions live only on the page, but eventually their short definitions will be shown on hover across the entire site. This helps developers learning Dart to avoid context switching while providing them useful information if they need.

To support that functionality as well as help developers better understand and discover important terms today, we'd like to add glossary entries for terms relevant to Dart, contextualized to Dart and its surrounding ecosystem. We'd love your help to document terms you know well or found important in your Dart journey. We're beyond happy to help review and edit your change, bringing your expertise to Dart developers of all calibers.

Glossary entries are added in the glossary.yml file.

Glossary entry format

Each entry in the glossary.yml file has the following fields:

Expand for format, purpose, and options of glossary entries

• term (required)
  The term the entry is for. Can be multiple words, but should preferably fit in one line.

• short_description (required)
  A 1-2 sentence description of the term in the context of Dart. The description should provide enough info to refresh someone previously familiar with the term and enough info for anyone to determine if they want to learn more.'

• long_description (optional, but recommended)
  A full description of the word in the context of Dart and/or Flutter. Can be written in standard Markdown, with cross-links, code blocks, etc.

• labels (optional)
  A list of up to 5 relevant labels to enable filtering and categorizing this term. While this is optional, it’s best to provide at least one label. You can reference existing labels in the file to align with them and for inspiration, but feel free to use other ones that you think will aid discovery.

• related_links (optional)
  A list of links to resources related to the word. Resource don't have to be on the Dart site, but should be reliable and reputable. Each resource has the following information:

  • text (required)
    A descriptive link text, such as the title of a page or video.

  • link (required)
    The link of the resource.

  • type (optional)
    The content type of the resource to help readers understand its usefulness to them. Currently the following resource types are supported, but I'm happy to add support for more if necessary:

    • term (for other glossary entries or word definitions)
    • article or doc (general for doc pages)
    • tutorial (for tutorials, codelabs, etc.)
    • api (for API links)
    • video (for videos, such as links to Youtube videos or streams)
    • code or sample (for code samples or repository links)
    • diagnostic or lint (for links to specific lints, diagnostic docs, etc.)

• alternate (optional)
  A list of other terms that this term might be known by, even if not technically/exactly correct. Used for improved search results.

On the Dart site, our writing follows the Google developer documentation style guide and we try to stick under 80 characters per line. You can try to follow these guidelines, but we're happy to make any necessary adjustments to match them, so don't worry too much.

Potential terms to add

We'd love you to add any term(s) that you are most interested in or feel most comfortable contributing. Just remember that terms should be relevant to Dart developers and explained in the context of Dart. If a term doesn't come to mind, but you'd still like to help, consider documenting a term from this idea list:

Expand for a non-exhaustive list of Dart-related terms to add

• Aggregate type
• Allocate
• AOT
• Asynchronous
• Bottom type
• Breakpoint
• Callback
• Closurization
• Combinator
• Dependency graph
• Dill (file)
• Downcast
• FFI
• Heap
• Identity
• IIFE
• Immutable
• Implicit cast
• Initializing formal
• Instantiation by bounds
• Interop
• Isolate
• Isolate group
• JIT
• Kernel
• Lambda
• Late
• Lockfile
• Microtask
• Native platform
• Null safety
• Package config
• Reference
• Scope
• SDK
• Semantic versioning
• Shadowing
• Snapshot
• Sound
• Synchronous
• Tear off
• Top type
• Tree shaking
• Type alias
• Uninitialized
• Web platform
• Wildcard
• Zone