Great post from CT Smith at docsgoblin.com:
At a previous role, WE WANT DOCS LIKE STRIPE was directed at me, with full eye contact during a meeting, by a leadership team that refused to give me any money for tooling or development resources. I cracked and said “Stripe has like seven engineers on their doc tooling alone, I’m not sure what you expect from me with my current resourcing. Could you help me prioritize?”
I left shortly after this conversation. Trust, it’s been one of many times I’ve heard this in job interviews, chats with founders, really any conversation about documentation where the tech writers were outnumbered. Tech writers love lambasting this request when we get together to talk shop, pointing out that companies always want docs like Stripe’s, but but they don’t ever want to invest in docs like Stripe does.
It’s important to leverage expectations with the resources available, and the unfortunate truth is that companies tend not to have as many resources going towards their documentation. This is true not just for resources like investment or team members, but also in providing time and tools for people to onboard to your systems. I pretty clearly list the tools I’m comfortable with on my resume. I can adapt and learn new tools, but you’ll have to give me time to get up to speed with them — and this can be both the things that are documented by your vendor, but also the things you’ve built inside of it. And my first pass is not going to be at a professional level.
It’s also important to note what goes unsaid when someone relies on comparison and focuses on the presentation layer:
People who say this think that the docs are in the “look” or the tool used to build them, or even their perceived comprehensiveness or complexity. They think things like this:
- If we have the same tool Stripe uses for their docs, our docs will be that good too!
- If we make the docs look like Stripe’s, our docs will be good too!
- If we have a lot of docs like Stripe, our docs will be good too!
They see the finished product, without any understanding of the kind of work and care that it took to bring it into existence, and say “Yes, just like that!” and then try to reverse engineer it based on appearances without ever going beyond the presentation layer.
Definitely a good reminder that indirect reference through an example is a bit of a shortcut in communication, and we should always strive to communicate more clearly.