Trouble writing tech docs and RFCs

You can see a real, detailed system design doc in the course: System Design Masterclass: Shipping Real Features To Production.

One simple way to improve your docs is to use a template, which forces a level of thoroughness and depth that will be valuable. You can find a lot of these online: Taro community member Jordan Cutler put a tool together for this: https://www.writeedge.ai/

If you happen to use Confluence internally, they should have templates already.

I also found Inverted Pyramid: Writing for Comprehension useful.

Here are a couple of samples to look through for more ideas and comprehensiveness:

1. https://rfd.shared.oxide.computer/rfd/0053

2. https://rfd.shared.oxide.computer/rfd/0110

What you can also do is browse the internal RFCs and tech docs to find the good ones and think about what they do well. It's also fair game to reach out the authors and ask about their process.

This is something you get better at through practice.

For getting better at writing design docs

• Put in volume, write many docs, and get feedback often from accomplished people that you trust.
• Look at other people's docs and look at the feedback they have received
• Also mentioned here, it's fair to reach out to others and ask about their thought process
• Make a note of any acronyms that you repeatedly see in these docs and ask what they mean as well as perhaps document it in a wiki page for newcomers to more easily figure out

Thanks 🙏🏼 appreciate it