Skip to main content

TechDocs

Adding Documentation with TechDocs​

TechDocs offers the ability to supplement your programmatically ingested data with markdown based documentation. If both TechDocs and entity overlays are enabled, then you can add the required annotation to connect the programmatically ingested entity to a docs repository in github.

Rationale​

Utilizing TechDocs allows data owners to make their documentation visible, searchable, and connected to their dataset entities in Portal. Because AiKA supports TechDocs as a source, taking these steps enables Portal users to ask AiKA questions about datasets in their data ecosystem. If documentation doesn't exist yet, or lives in an external source, admins could create a campaign in soundcheck to have data owners add documentation for their datasets, potentially on the most critical and widely used tables to start.

Configuration​

To set up documentation with TechDocs:

  1. Create a github repository accessible with the credentials the portal instance was configured with.
  2. Follow the instructions here to author the documentation markdown files and mkdocs.yml inside the repository. Ignore the steps about populating a catalog-info.yaml (since dataset entities aren't derived from one!).
  3. Using the Edit entity overlay button in the top right ellipses menu on a dataset's entity page, add backstage.io/techdocs-ref as an annotation key, and url:https://$GITHUB-HOST/GITHUB-ORGANIZATION/GITHUB-REPOSITORY/tree/main/ as the value.
  4. Note that you can put documentation for more than one dataset in the same repository, updating the URL paths to point to the top level folder which contains relevant information for dataset(s).

For example, imagine a company foo had an enterprise github instance, and organization titled 'data-eng', and a new repository 'docs'. If that company populated the repository such that the folder structure looked like this:

all-documentation/
  bar-docs/
    docs/
      index.md
    mkdocs.yml
  foo-dataset-documentation/
    docs/
      index.md
    mkdocs.yml

then the following entity-overlay would ensure the docs tab on the dataset entity becomes populated with the contents of bar-docs' index.md.

Example Overlay Adding TechDocs annotation