Determine and document best practices for displaying YAML data in documentation body content
Problem
Large tables of data are often best maintained through a structured data file, such as a YAML file, the most common format for a static site environment:
- YAML can be easier to read than markdown for larger sets of data, given the inherent structure, whereas markdown accepts any column widths per line, and rows can grow very wide (or wrap in text editors) making them hard to view or edit.
- It is difficult to author markdown tables with consistent fields and formatting; not so with YAML, where a hierarchy and consistent use of field ('key') names on each object ('dictionary') is clear.
- YAML can be tested for consistency, for example, 'does attribute (column) X always have a URL'? This results in better, more consistent content for readers.
- A YAML file can be used as a single source, with different attributes displayed in different contexts (multiple pages or tables).
- It is easier to automatically generate YAML from other data sources.
YAML can already be displayed in custom layouts such as tables on about.gitlab.com.
It's unclear if we can insert a table in a documentation page that's built from a YAML file.
Proposal
- Determine and document a method for including YAML-based data in documentation.
- The left nav is built from YAML so perhaps we can use the same method in docs content.
- From the Nanoc docs it looks like you can render a layout as a partial.
- It is possible that we may want to display YAML data in other formats in the future, but a table would be the most common, so should be the MVC.
- As proof of concept, and to fulfill a need in the documentation, start by converting the cleaned-up Event Dictionary data (WIP) to YAML and using this method to display it back on the Event Dictionary page.
Note: It is unlikely we would implement/support this in the current <gitlab.instance>/help
view of documentation. We'd have to wait for gitlab#214164 (closed) for a full rollout. The first intended usage is on a page for contributors, so perhaps there is a way for the table to fail gracefully on /help
and point to the public doc.
Edited by Mike Lewis