README for The AI Alliance Glossary

Published Documentation

This repo contains the GitHub Pages documentation for the AI Alliance Glossary, a shared resource across all our websites, providing definitions for common terms.

See the repo README for additional details.

The rest of this README provides information for contributors, developers, and users of this project repo.

Adding or Editing Terms

All the terms are defined in a giant YAML block at the beginning of docs/index.markdown. If you edit the terms defined there or add new ones, here are a few tips to work around problems parsing the definitions as YAML (also in a comment in that file). Using YAML declarations for this content definitely has pluses and minuses...

You may see obscure messages at the Jekyll console like this:

YAML Exception reading /Users/deanwampler/ibm/ai-alliance/repos/others/glossary-git/docs/index4.markdown: (<unknown>): did not find expected key while parsing a block mapping at line 338 column 5

It could be one of several things on line 338 (in this example):

• A : was used at the end of a sentence (especially at the end of a paragraph). Sometimes the colons are interpreted as key-value YAML delimiters (but not always). Use : instead (or use a period). Note, it appears that : doesn't work!
• You have some leading tabs in front of the key-value definitions. It may actually be that you can use tabs or spaces, not mix them, but I replace all tabs with spaces.
• You used a Markdown-style block quote (e.g., > foo\n> bar) in a definition. Replace it with an HTML blockquote. See an example in the definitions in docs/index.markdown.

Other tips:

• For lists, only use ordered lists with 1.; don't use * or - bullets. This causes a weird behavior where those bullets are rendered by themselves down the page, well past the term viewer, causing the browser to show a big scroll bar with nearly empty content below the term viewer! "Nearly empty", because you notice groups of dots if look carefully. Just use numbered itemized lists...
• Put two blank lines between paragraphs. If you put just one, they will be joined into one paragraph when parsed by Jekyll's Liquid and/or Markdown engines. (I tried code hacks to fix this when loading, but nothing worked.) The single blank lines between the YAML blocks (e.g., the one between "Vibe Engineering" and "Zero-Shot Prompt" at the end of the YAML block in docs/index.markdown) are purely for legibility and have no affect on rendering.

Getting Involved

We welcome contributions as PRs. Please see our Alliance community repo for general information about contributing to any of our projects. This section provides some specific details you need to know.

In particular, see the AI Alliance CONTRIBUTING instructions. You will need to agree with the AI Alliance Code of Conduct.

The glossary is licensed under the Creative Commons Attribution 4.0 International (which is also in this repo, LICENSE.CC-BY-4.0).

Quick Tip - View the Website Locally

See GITHUB_PAGES.md for information on viewing the site locally with jekyll.

We use the "Developer Certificate of Origin" (DCO).

Warning

Before you make any git commits with changes, understand what's required for DCO.

See the Alliance contributing guide section on DCO for details. In practical terms, supporting this requirement means you must use the -s flag with your git commit commands.

About the GitHub Pages Website Published from this Repo

The website is published using GitHub Pages, where the pages are written in Markdown and served using Jekyll. We use the Just the Docs Jekyll theme.

See GITHUB_PAGES.md for more information.

Note

As described above, all documentation is licensed under Creative Commons Attribution 4.0 International. See LICENSE.CC-BY-4.0).