Documenting configuration directly on the config file is great, right? Everything is right there.

Ehh.

This could probably be repackaged.

Why embark on this journey?

You can Ctrl + F (or Command + F) your way through the file, but you have to know what you are looking for.

You could argue an intuitive experience and naming strategy would work well in this situation, but that's a stretch, particularly when talking about advanced config. A great goal, but really difficult.

For first time users, you are likely going to walk through this template, uncommenting out the config you do want to use. You may take the opportunity to stop and read along the way, but I'm thinking reading nearly 1000 lines and trying to retain keywords for future changes is just not going to work for most people.

So let's get this presented in another way to maximize visibility and gain some of that sweet SEO and searchability people are used to these days. You'll cover the use cases where people go back to the config template directly and get it backed into the docs.

YAML to HTML

From this issue comment:

The template YAML as-is was hard to consume. Nearly everything is commented with # (except flush?) I had to start by copying the file locally and removing the comments for it to be valid YAML.

From there, I took the lazy(ish) approach and used https://github.com/ishswar/yaml-to-table, which didn't work without some changes. Instead of copying the descriptions, it added ipsum... ugh.

I found this project that got me from YAML to HTML. It wasn't perfect since it didn't copy the descriptions, but I'm not above putting on some background noise (music, podcast, etc.) and copy and pasting my little heart out.

HTML to Markdown

Since our docs are in Docusaurus, I could have left the tables in HTML, but once they were in HTML the move to Markdown is pretty well supported by various free tools.

I used TableConvert which takes a bunch of different formats. Just be careful with what you put into any tool! None of this info was sensitive or private.

Wrap up

Could I have done this in a more streamlined or automated way? Likely.

Will I invest the time to script this? Unlikely.

I view this as a one time project with how stable the templates are and how little things change regularly in this space. If we were often adding, removing, or deprecating this config, I would certainly be more motivated to get this automated to go from YAML to Markdown with as little touches as possible.

Have you done something similar? Do you read or work with YAML often? How do you prefer to read documentation on YAML config?

Cover photo by Elevate on Unsplash