Adding a glossary term

Fuchsia.dev uses a yaml glossary-yaml file to define all Fuchsia specific terminology.

This format allows Fuchsia to use single-source definitions to be edited in a single location and updated throughout the documentation. These definitions can then be used throughout documentation using documentation widgets, which then allows you to use inline definitions or full definitions in your documents.

Additionally, Fuchsia has a main filterable glossary page.

Add a glossary entry

To add a glossary definition, you need to edit the yaml glossary-yaml to include information about your definition:

Reference

Glossary definition
termRequired

Define the glossary term.

short_descriptionRequired

Define a short description for your glossary term. This definition must be short, preferably a single sentence. This definition can then be used to have definitions as hover-over text.

You must use HTML syntax. However, if you have a simple definition that is a single sentence or paragraph, you can use plain text.

For example, this is the definition for the term ABI .

full_descriptionOptional

Define a full for your glossary term. This description should be complete and fully explain the term.

You must use HTML syntax, including for links. However, if you have a simple definition that is a single sentence or paragraph, you can use plain text.

For a link, use this format:

<a href="link_location">link_title</a>
see_alsoOptional

Create a list of related links for the term. This can be links to other terms or related documentation. You must use HTML syntax.

  • For a single link, use this format: 
    ['<a href="link_location">link_title</a>']
  • For multiple links, use this format: 
    ['<a href="link_location">link_title</a>',
['<a href="link_location2">link_title2</a>']
related_guidesOptional

Create a list of related guides for the term. This should only be links to guides located in //docs/development/. You must use HTML syntax.

  • For a single link, use this format: 
    ['<a href="guide_location">guide_title</a>']
  • For multiple links, use this format: 
    ['<a href="guide_location">guide_title</a>',
['<a href="guide_location2">guide_title2</a>']
areaRequired

Define a list of the areas that your glossary term pertains to. These areas make the glossary terms filterable on the glossary page. You must use HTML syntax.

  • For a single area, use this format ['area'].
  • For multiple areas, use this format ['area1', ...]

Valid areas

Valid areas
  • Bluetooth
  • Build
  • Component Framework
  • Developer
  • Devices
  • Diagnostics
  • Driver SDK
  • Drivers
  • EngProd/Infra
  • Experiences
  • FIDL
  • Firmware
  • Foreign ABI Compatibility
  • General
  • Governance
  • Graphics
  • HCI
  • Identity
  • Kernel
  • Languages and Libraries
  • Media
  • Memory
  • Metrics
  • Netstack
  • Performance
  • Power
  • Recovery
  • Security
  • Sessions
  • Software Assembly
  • Software Delivery
  • Storage
  • System
  • Testing
  • Toolchain
  • View System
  • Virtualization
  • Web
  • WLAN

Sample

- term: 'ABI'
  short_description: 'The binary-level interface to the system.'
  full_description: 'The <a href="/docs/concepts/packages/system.md">Application Binary Interface</a> (ABI)
  for a system is the binary-level interface to the system. Typically you don''t
  write software that uses the system ABI directly. Instead, you write software
  against the system API. When the software is compiled, the binary artifact
  created by the compiler interfaces with the system through the ABI.
  Changes to the system ABI may require you to recompile your source code to
  account for the changes in the ABI.'
  see_also: ['<a href="/docs/glossary#ABI">ABI</a>',
             '<a href="/docs/glossary#storage-capability">Storage capability</a>']
  related_guides: ['<a href="/docs/development/tracing/tutorial/registering-a-trace-provider.md">Registering a trace provider</a>',
                   '<a href="/docs/development/hardware/paving.md">Installing Fuchsia on a device</a>']
  area: ['System', 'General']

Once you have created the entry for your glossary entry and submitted the Gerrit change, your glossary term will be visible on the glossary page and usable as a documentation widget.