Ask HN: What is the best config file documentation you have seen?

30 points by caarlos0 3 years ago | 12 comments

I run a project called goreleaser, which is configurable via YAML.

Since it has a lot of options, it can get confusing. I do provide a JSONSchema and a documentation page, with all available options and some commented examples.

Still, I feel like it could be better - especially regarding informing in which version a given option was added, discoverability, etc.. I'm just not sure how to make it so.

That said, I wonder: what is the best software configuration documentation you have ever seen?

ksaj 3 years ago |

The config file for sendmail used to be really quite good. There were more lines of explanation than there were config items. There were numerous documented example lines describing several different, but common setups. There were explanations about why you may or may not want a particular line item. There was even a preliminary mailing list handler built into the config documentation, should you want to run such a thing. It was so well documented a beginner could edit it successfully, as long as they already knew how to get out of Vim.

This was quite a feat, considering most people only ever saw m4 language in sendmail configs. It's not very easy to read.

caarlos0 3 years ago | |

Oh, I’ll take a read! Thank you

yrgulation 3 years ago |

FreeBSD’s config files spring to mind. Here is an example:

https://github.com/lattera/freebsd/blob/master/etc/defaults/...

Also relevant is this quote from john romero, id’s co-founder:

“Bulletproof your engine by providing defaults upon load failure.”

https://www.mcvuk.com/development-news/john-romeros-secrets-...

caarlos0 3 years ago | |

That quote is quite good indeed! Thanks for sharing it and the example config.

llIIllIIllIIl 3 years ago |

php.ini

Seriously, that is usually the easiest configuration i had to deal with. Although there are hundreds of configurable options, each one is thoroughly documented in the same file.

Yaml config, although being better structured, rarely have any comments with explanation, and I’m still waiting to see one documented at 30% of php.ini.

notRobot 3 years ago | |

Came here to say this. Configuring php.ini is actually fun for me. I love reading through everything in the file and often end up learning new stuff!

For those who've never seen it: https://github.com/php/php-src/blob/master/php.ini-productio...

citrin_ru 3 years ago |

Nginx config documentation is one of the best I've seen. Things I like which are not common: 1. It specifies in which version a feature was introduced (if it was not present if first public release) 2. It is easy to send a link pointing to description of a specific directive e. g. http://nginx.org/r/env 3. For each directive docs tell a default value. It seems obvious that any decent documentation should have this but I've seen software for which it is hard to find out default values so you have to add into config many values just in case even if they are not different from defaults.

minhmeoke 3 years ago |

The Dhall config language has a very persuasive landing page (https://dhall-lang.org/), nice docs (https://docs.dhall-lang.org/tutorials/Getting-started_Genera...), and also a great philosophy of preventing errors through correct design: https://docs.dhall-lang.org/discussions/Safety-guarantees.ht...

tomcam 3 years ago |

Would you mind reaching out to the email address in my profile? I have some strong feelings about it and fancy myself a decent docs person. A couple of public things I've done are at https://tomcam.github.io/postgres/, https://vuepressbook.com, and https://tomcam.github.io/least-github-pages/. I have just begun using goreleaser a few days ago so I have a good perspective.

joshxyz 3 years ago |

eslint config is great, you can use json or js or other formats, works well.

dylanhassinger 3 years ago |

i like .js config files, easy to add comments

yuppie_scum 3 years ago |

Just yaml please, or JSON.