[thundergolfer]

Last year wrote a technical writing advice checklist for engineers called How to ask for help in Slack: https://thundergolfer.com/communication/slack/2021/02/24/how....

I was at Canva, a fast growing company adding 500 engineers a year, and the tenured engineers were getting hit with a lot of questions and help requests.

I thought about this list a lot, and believe that maintaining adherence to all 10 checklist items will dramatically improve your technical communication in chat apps.

For advice on writing long form communications, my absolute favorite resource is LEADERSHIP LAB: Writing Beyond the Academy[1]. This lecture will cleanse you of all the bad writing ideas you picked up in 12+ years of schooling, and show you actually how to think about professional writing. I've watched it about 4-5 times.

1. https://www.youtube.com/watch?v=aFwVf5a3pZM

[TillE]

The problem with stuff like this (or ESR's How To Ask Questions The Smart Way) is that they only really get through to the people who care enough to want to improve themselves and their interactions, which is probably like 1%.

Maybe it's easier if they're employees. But my overwhelming experience out there in the wild is that people ask terrible questions which can't be answered, because they put zero effort into anything.

[luckylion]

FWIW we've had a lot of success when we created a wizard-style system for normal users. It's mostly web-apps, so we'll ask for the URL, we'll ask them to paste a screenshot and encourage them to draw on it, we'll ask them to ELI5 what they did/did not expect to see etc, and on submit we'll automatically collect some additional information e.g. on a public website we'll get an HAR of the page + resources at the time of the report.

Just forcing a URL, screenshot + expectation has improved reports drastically. Before, we'd get a partial screenshot that shows some random widget where nobody knows the URL it's from, or what it should be looking like, or whether it's actually something that looks wrong, or just something that's worded incorrectly, or that there should be a link on some term in a text.

[thundergolfer]

I somewhat agree, but where I worked people were motivated to improve themselves, and you can't build an effective organization assuming your new hires don't care; you at least have to try.

(ie. I can't go to my manager only ever with complaints and no action)

[galoisscobi]

This is an excellent guide. Thank you for taking the time to write it. I wish I had something like this when I started out in tech but helpful people early on taught me about not sending screenshots and sent a link to the XY problem explainer page.

[thundergolfer]

Thanks :) I hoped to turn my petty Slack frustrations into a helpful bit of shareable guidance.

[fortylove]

I usually dislike processes like what you describe as they normally just add friction, even if there are good parts. But as a senior eng, I find your list very good. Thanks for sharing!