Hacker News Reader

Comment by hartator | Hacker News Reader

Start with a small praise and how the project had currently helped you. Even just a "Thank you for this awesome tool!" goes a long way.

Do a bit of story telling about why you want this or that. Try to make a good case of it.

Post as most as possible, code, backtrace, steps to reproduce, what did you tried, etc. In a structured way.

Assume you may be wrong. Use words like "Maybe", "We probably should", "I may be misguided, but", etc.

Format it correctly, check for spelling and errors.

Finally, reply back when asked for stuff.

It's not that hard, but most people aren't doing it.

View on HN

This is just a general front line support problem. A poor problem description or incomplete problem description is irritating and gets to people. The other one is the people that only show you step #4 of a procedure they are using and keep trying to point to that as the root cause while it was really step #2. An issue report should show from damn near install to the observed problem, or thorough enough logs/config/stacktrace to give people on the receiving side enough information on how you got here. I call this the A-B-C-D problem, where they only keep telling you about something breaking in C but nothing about A, B or D that feeds in.

The assume you may be wrong attitude to take in problem description is definitely something I have seen well received as a reporter and a recipient. Issues that are submitted with a tone of finality and then it turns into a problem resolved by configuration/FAQ/documentation can be frustrating, because in the triage you have to ignore such language and verify anyway.

The unassertive language also clues the reader of potential knowledge gaps in the reporter. Inevitably just by construction of the report

Also this was something that was mentioned in postgres response after I believe Uber transitioned from the technology to MySQL recently- if you are doing something massive/slightly insane it helps build a strategy. A communication issue from VPS host to VPS host for MySQL will require a different diagnostic strategy than microcontroller to microcontroller MySQL connection over an TCP/IP on I2C bus duct taped to the bottom of a Honda Civic.

Hopefully this Issue/PR [1] I opened today to clarify documentation would make good live example of this :-)

[1] https://github.com/BurntSushi/ripgrep/issues/284

> Start with a small praise and how the project had currently helped you. Even just a "Thank you for this awesome tool!" goes a long way.

This might be good advice in general, I'm not sure, but I mostly see this as just noise and it won't make me more likely to respond quickly or take any action. In terms of politeness, I think the more relevant quality is how entitled you come off as. If you come in saying, "This needs to change because of <downstream product requirement>", it makes me think you probably are thinking of the change in terms of how it helps you. If you come in saying, "This is the problem I'm having, this is the workaround I came up with, but this doesn't seem like the right behaviour because <x>", I'm more likely to figure that you actually took a holistic view and are thinking about how this change would affect all downstream users.

Other than the bug reproduction instructions it seems like you could train a piece of code to convert requests to a format like this using machine learning. It could save someone from a lot of stress! (I agree with your point but even solving it this way would provide benefits).

Reply on news.ycombinator.com