Ask HN: Technical Writing Resources

11 points by stevenking86 1 year ago | 5 comments

I'm an engineering manager in an organization where the current culture is extremely meeting heavy. Decisions are made in meetings, discussions take place in meetings, etc. It's not very practical as our team is distributed across the globe.

I've been in more asynchronous organizations and I'm making some attempts to steer the culture in that direction. However, one component that I think is extremely necessary for this to work is for the team to become good writers. If we're communicating in Notion, tickets, and pull requests then we need to improve as writers.

I've searched around and so far mostly found click-baity type articles like "10 ways to do better technical writing". Does anyone have any helpful resources for individuals and teams to improve at this? Thanks!

fabianholzer 1 year ago |

Well, it is hard to change a company from the oral/meeting-driven style to an async writing-based culture and a fear even the best resource won't really help with that. But since you've asked also on an indiviual level, I found some nuggets on technical writing in https://jamesg.blog/2024/01/03/software-technical-writing/ - certainly way better than a SEOed listicle

chbint 1 year ago |

I honestly don't think you'll be able to get very far unless the team is already onboard with the plan to switch towards a more asynchronous culture. If they lack the motivation, they won't bother improving their writing.

The tricky part is that they might be interested in the results you promise, but still lack motivation. It's common for someone who's interested in losing weight not to be very motivated to do it themselves. They don't want to lose weight themselves, they want to "be slimmed down by someone else". You may face a similar difficulty. That's part of the reason why changing a culture is so hard.

I know that's not a direct answer to your question, but I needed this context to say this: I think whatever tricks and tips you can come up with yourself are more likely to succeed. That's because you're already familiar with the specific needs and the specific difficulties people might face when handling the most frequent and repetitive issues.

Rather than thinking how to get fuzzy improvements on people's overall writing skills, perhaps you could try to focus on suggesting specific solutions for specific problems ("hey everyone, I've noticed that when handling X people usually forget to tell p, q and z. So let us agree on using this text structure '1) p; 2) q; and 3) z; whenever handling X"). I think that, by accumulating lots of small tricks like these over time, you'll be able to go further. Going bottom-up seems easier than trying to change things top-down.

I'm not sure this makes sense to you, for I'm not familiar with your concrete situation, but I hope it helps somehow.

kingkongjaffa 1 year ago | |

I think, like OP that:

> I've searched around and so far mostly found click-baity type articles like "10 ways to do better technical writing".

So I hoped that there has to be a better way or silver bullet somehow.

strongbond 1 year ago |

I've found https://diataxis.fr/ to be an excellent framework on which to hang documentation efforts. It helps you to understand what kinds of documentation resources help users most.

brudgers 1 year ago |

for the team to become good writers

Everyone else is not a good writer is the subtext of your views. Expressing that subtext will not win friends and influence people.

Improving meetings through writing is the place to start. Take it upon yourself to write, edit, distribute and revise the agendas. Take it upon yourself to write, edit, distribute and revise the minutes.

Show dont tell. Good luck.