3 ms·

Who reads though? We had a build prerequisite check that output "error: package xxx is out of date, run sudo apt upgrade - see wiki.local/XXX for more details"

Who reads though? We had a build prerequisite check that output "error: package xxx is out of date, run sudo apt upgrade - see wiki.local/XXX for more details" They still copied the error to me and asked what to do. I said follow the instructions in the message. They said cool thanks and did so.

ahaferburg 5y ago
The problem is not reading, it's trust in the information. You telling them that the information is up-to-date and valid and useful is the reason why they read it.
mooreds 5y ago
Did they do that once or multiple times?
lanstin 5y ago
You could have a whole career of actually reading the error logs in email chains and then just saying that error as a normal English email.
lovecg 5y ago
It seems trivial to you, but only because _you know to trust the message and what’s written in the wiki already_. The hardest thing about documentation is establishing this chain of trust. By coming to you and getting a verbal confirmation they establish one tiny link in that chain. Edit: just thinking out loud here. These error messages are equivalent to a random passerby without any skin in the game saying “oh just run this command” — how would one trust them when their job is on the line? I can think of a few common approaches: - “oh just run this command because paragraph 1.2.3 in the universal code we all agreed to says so” (easy to confirm) - “oh just run this command because senior engineer X said it’s safe” (assuming you believe that they did say that) So maybe the error messages should include some equivalent of those.
- bacro 5y ago
  Just now, one of the junior develops contacted me about a problem trying to start an application we are developing. I asked: "Did you follow the instructions in README.md file?". He said: "Yes". Then when I asked for him to show me the error, I could see he clearly had not made one of the steps in README to start the app. Just to confirm I asked if he had done it and he said: "No, maybe this is why I am getting this error then". I need a punch bag urgently...

ahaferburg 5y ago

The problem is not reading, it's trust in the information. You telling them that the information is up-to-date and valid and useful is the reason why they read it.

mooreds 5y ago

Did they do that once or multiple times?

lanstin 5y ago

You could have a whole career of actually reading the error logs in email chains and then just saying that error as a normal English email.

lovecg 5y ago

It seems trivial to you, but only because _you know to trust the message and what’s written in the wiki already_. The hardest thing about documentation is establishing this chain of trust. By coming to you and getting a verbal confirmation they establish one tiny link in that chain. Edit: just thinking out loud here. These error messages are equivalent to a random passerby without any skin in the game saying “oh just run this command” — how would one trust them when their job is on the line? I can think of a few common approaches: - “oh just run this command because paragraph 1.2.3 in the universal code we all agreed to says so” (easy to confirm) - “oh just run this command because senior engineer X said it’s safe” (assuming you believe that they did say that) So maybe the error messages should include some equivalent of those.

bacro 5y ago
Just now, one of the junior develops contacted me about a problem trying to start an application we are developing. I asked: "Did you follow the instructions in README.md file?". He said: "Yes". Then when I asked for him to show me the error, I could see he clearly had not made one of the steps in README to start the app. Just to confirm I asked if he had done it and he said: "No, maybe this is why I am getting this error then". I need a punch bag urgently...