2 ms·

> Perhaps I should have read the entire reference document for all the Dockerfile instructions first. I really, really hate to be "that one guy" (c) Rachel Kro

> Perhaps I should have read the entire reference document for all the Dockerfile instructions first. I really, really hate to be "that one guy" (c) Rachel Kroll, but... if you're about to use a large, old, complicated piece of software, the chances are very good that its developers have mental models about what is good software, and what is good documentation, and what is self-evident and what is not, that are very, very different from yours, especially if you're a programmer and the piece of software is aimed at the sysadmins/ops/devops — so yes, read the whole docs. The things are not what you would hope they are.

ponector 2y ago
And then go and read all issues logged to see how your mental model is different. Recent example I hit was a Gitlab pipeline. "When: always" setting for after_script does not mean the command will be executed always. Only if main section finished with either success or failure. If it is terminated by timeout or manually - no, script is not executed.
anal_reactor 2y ago
>so yes, read the whole docs Thanks to reading the whole docs an hour a day I avoided a bug that happens once a year and takes whole 30 minutes of debugging. "Correct practices" in a nutshell.
- MereInterest 2y ago
  Exactly. Documentation is useful when a user knows that there are multiple reasonable options for an implementation to take. "Which byte order is used for this protocol?" is a question that can occur to a user and can be looked up in the documentation. Questions like "Does this language require explicit imports to access variables in the parent scope?" are not questions that occur to a user, because any violation of that would be so unexpected as to be a bug. Docker documents its bugs, calls them the intended behavior, and then blames users for not reading about the bug in the documentation.

ponector 2y ago

And then go and read all issues logged to see how your mental model is different. Recent example I hit was a Gitlab pipeline. "When: always" setting for after_script does not mean the command will be executed always. Only if main section finished with either success or failure. If it is terminated by timeout or manually - no, script is not executed.

anal_reactor 2y ago

>so yes, read the whole docs Thanks to reading the whole docs an hour a day I avoided a bug that happens once a year and takes whole 30 minutes of debugging. "Correct practices" in a nutshell.

MereInterest 2y ago
Exactly. Documentation is useful when a user knows that there are multiple reasonable options for an implementation to take. "Which byte order is used for this protocol?" is a question that can occur to a user and can be looked up in the documentation. Questions like "Does this language require explicit imports to access variables in the parent scope?" are not questions that occur to a user, because any violation of that would be so unexpected as to be a bug. Docker documents its bugs, calls them the intended behavior, and then blames users for not reading about the bug in the documentation.