Chris's Wiki :: blog/tech/YamlPracticalDocumentationIssue
source link: https://utcc.utoronto.ca/~cks/space/blog/tech/YamlPracticalDocumentationIssue
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
A practical issue with YAML: your schema is not actually documentation
These days, YAML is used as the configuration file format for an increasing amount of systems that I need to set up and operate for work. I have my issues with YAML in general (1, 2), but in the process of writing configuration files for programs that use YAML, I've found an entirely practical one, which I will summarize this way: a YAML schema description is not actually documentation for a system's configuration file.
It's entirely possible to write good documentation for a configuration system that happens to use YAML as its format. But while showing people the schema is often easy, it's not sufficient. Even a complete YAML schema merely tells the reader what values can go where in your configuration file's structure. It doesn't tell them what those values mean, what happens if they're left out, why you might want to set (or not set) certain values, or how settings interact with each other.
(And people don't even always do complete YAML schemas. I've seen more than one where the value of some field is simply documented as '<string>', when in fact only a few specific strings have meaning and others will cause problems.)
I don't know why just dumping out your YAML schema is so popular as a way to do configuration file 'documentation'. Perhaps it's because you have to do it as a first step, and once you've done that it's attractive to add a few additional notes and stop, especially if you think the names of things in your schema are already clear about what they're about and mean. Good documentation is time consuming and hard, after all.
I suspect that this approach of reporting the schema and stopping is used for YAML things other than configuration files, but I haven't encountered such things yet. (I've only really encountered YAML in the context of configuration files, where it's at least better than some of the alternatives I've had to deal with.)
(All of this assumes that your configuration file is as simple as a set of keys and simple values. Not all configuration files are so simple, but systems with more complex values tend to write better documentation. Possibly this is because a dump of the schema is obviously insufficient when the values can be complex.)
Recommend
-
7
Modern software controls dependencies because it helps software authors February 20, 2021 Over on Twitter I had a hot take:
-
8
TLS certificates have at least two internal representations of time June 6, 2021 TLS certificates famously have a validity period, expressed as 'not before' and 'not after' times. These times can have a broa...
-
8
There are (at least) two types of package managers September 14, 2021 These days, it seems that everything has a package manager (or package management system). Linux distributions and other Unixes have long...
-
3
I'm unsure of the security of simultaneous multithreading on modern x86 CPUs November 11, 2021 We're planning to get some high core count machines to be new compute machines in our environment of general mult...
-
1
A realization of why email is critical infrastructure for the Internet December 28, 2021 Like many people who've been on the Internet for a long time, I view email as a critical thing in the overall Internet...
-
8
My distrust of multi-factor authentication's account recovery story July 10, 2022 A bunch of third party websites really want you to use multi-factor authentication these days. Some of them aren't g...
-
5
Why being able to partially distrust a Certificate Authority is good December 6, 2022 One of the arguments I've heard against supporting partial distrust of Certificate Authorities in places like L...
-
8
An instruction oddity in the ppc64 (PowerPC 64-bit) architecture January 20, 2023 Over on the Fediverse, I reported my disco...
-
7
How AMD killed the Itanium July 15, 2005 I've been telling people versions of this story for a while, so I figure I might as well write it down for posterity (or at least entertainment). Whe...
-
7
DNSSEC failures are how you get people to disable DNSSEC May 31, 2023 The news of the time interval is that the people in charge of the New Zealand country zones (things directly under .nz) fumbled...
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK