A tech writer on my team was kind enough to share some words of wisdom with me after she saw a doc I wrote that mildly displeased her.
She told me:
Nothing is easy
Running a managed Kubernetes cluster is not easy. It may be easier than running your own cluster on bare metal. It may be the easiest solution you’ve come up with. But it certainly isn’t easy. Planning a vacation throughout Europe is not simple. It may be simpler than planning a vacation across Europe and Africa. It may be the simplest vacation you’re considering. But it isn’t simple.
While some words are “correctable”, others are not. One does not just launch a production-ready service. Don’t cause imposter-syndrome-flare-ups by saying it’s trivial to make a database schema migration even if we have docs for it.
In general, try to assume less about your readers. When I read technical docs, I usually know less about the subject than the author. I assume the same dynamic exists when I write things. Don’t be condescending and assume your readers know nothing. But also don’t assume your reader could write the doc instead.
Maybe productionizing your service is easy for your infrastructure tech lead who writes Terraform configs for breakfast, lunch, and dinner. But it probably isn’t easy for the engineer who you’ll hire in six months and has never heard about Terraform and the wonderful things it can do. An engineer who knows a lot about your niche is happy to skim over a glossary of terms and not click on that extra link to learn more about the wonders of Terraform. But that senior frontend engineer (who churns out gorgeous designs you can’t even dream of making) might be curious about how your team’s infrastructure works and they’ll be overjoyed to learn more about it without pestering you with easy questions.
If you don’t consider my writing a form of spam, consider getting emailed when I write stuff: