Documentation at scale: A conversation with Snowflake’s Rob Gray
Snowflake writer Rob Gray explains how to structure docs at scale, track documentation metrics and ROI, and prepare for an AI-driven, docs-as-code future.
Rob Gray is a Senior Technical Writer at Snowflake, where he works as what the team calls a “floater” — moving between different product groups thanks to his ability to pick things up quickly and learn rapidly. With a background that includes working at Oracle alongside a dedicated information architecture team, Rob brings both technical depth and strong relationship-building skills to his documentation work.
We sat down to discuss what makes documentation high-quality, the importance of making docs accessible and prominent, and how he sees AI changing both the creation and consumption of technical documentation.
Can you tell me about what makes a good documentation site, particularly in terms of structure?
That’s a good question. I have a real interest in information architecture — that started when I was working at Oracle, because I worked with the team dedicated to information architecture. If you’re just talking generically about how documentation is provided on the website, Snowflake does this very well. A lot of companies do it well. They make their documentation very prominent and easy to find.
Some companies put it behind almost like a paywall where you have to have a username and password. But I’ve never been a firm believer in that. I think the documentation should be accessible, unless you’re working in an industry like defense or something like that where of course you have to have it less accessible. But for me, I think documentation should always be accessible. It should be prominent.
Snowflake is one of those companies who does this — they’re very proud about their documentation, so they make it easy to find and easy to locate. We also solicit feedback constantly on our documentation. We’ve been told that Snowflake documentation has actually helped close deals, because they’ve looked at the documentation and compared it with other companies. So the fact that they’re able to locate it, to review it, and to determine the quality is a really good thing for our customers.
What are the components of that quality you mentioned?
Speaking personally, but in general terms too — the documentation has to be accurate. I mean, it sounds like a silly thing, but the documentation always has to be accurate, because users will get frustrated really, really quickly and turn off. They’ll think that in general terms the product itself isn’t good because the documentation isn’t good, or that the company simply doesn’t care. So it has to be accurate.
It has to be tailored for the specific audience. If you’re writing for a developer audience, you shouldn’t be providing a lot of narrative and explanatory text necessarily, like conceptual information, because a lot of the time developers just want to solve a problem and do it quickly. They don’t really want to spend time reading a lot of narrative or learning. Whereas a more general audience, general users, will want that conceptual information. They’ll want to take the time because they’re using it more for learning.
Also, presenting learning content in the right format — like putting it in a tutorial rather than putting it into a procedural topic where you have 16 paragraphs of introductory or conceptual information before you read the procedure. Making sure that content is appropriate for the audience it’s intended for is really important.
Layout and design is also important. How content is organized on a page. Is there enough white space? Are the headings differentiated enough so that you know what a primary heading and secondary heading is, so you know the relationship between things? Is it easy to scan? Are there navigational aids that allow you to quickly jump from the top to the bottom of the page? Can you provide feedback? All of those things make really good content, and you really have to think about those things.
We’re fortunate at Snowflake that we have a team that’s responsible for maintaining our style sheets and everything else, our infrastructure and our build environment. Not everybody is so fortunate. So we have that luxury to take the time to make sure that our documentation is always of the highest quality.
And can you tell me about the organizational approach to docs at Snowflake? How do you work with product and engineering teams?
Every product area, like a lot of companies, has a product manager, and then there’s an engineering team associated with that. As a writer, I work directly with both groups. I work with the product managers to discuss what the requirements might be for a new feature or an enhanced feature, and what documentation is required. Then usually the engineering team’s providing me with source content or access to an instance where I can do testing.
It’s a back and forth. I personally involve the product managers or PMs and the engineering team with all my writing reviews. We conduct everything here in GitHub. We have a docs-as-code type environment. So I’ve actually been responsible for making sure all the PMs have accounts and can access our repo and can do reviews.
It’s a very close relationship with the engineering teams and product managers. I work with them daily. The relationship development part of my job is critical. I have to develop strong relationships. If I destroy a relationship with a PM or an engineering team, or I damage it in some way, it’s going to be really hard for me to do my job.
How does that workflow typically work? Is it the PM saying “we’re thinking about building a new feature” or is it “here’s the feature, go document it”?
It works in both ways. We work in an agile environment, so the product managers and engineering teams are encouraged to open up Jira tickets for the writers. In those Jira tickets, they’re supposed to provide as much information as they can about the ask — about what new documentation is required, why it’s going to be of benefit, and also links to source documents. I also ask that they identify the subject matter experts who are going to be responsible for reviews and technical questions and things like that.
It depends on the writer. Some writers are less formal, some writers are more formal. But usually the PM will approach me and say, “Hey Rob, in a month or two we’re going to be having this new feature or we’re going to be enhancing this feature. I wanted to give you a heads up.” And then I’ll have the conversation saying, “Okay, please open a Jira ticket, and we’ll meet occasionally to discuss it.” But I’ll prepare a first draft, and then the review cycle starts from there.
At a senior level as a writer, you’re expected to produce content pretty quickly and independently without a lot of hand-holding. So that’s what the expectation is, and I try to do that.
How do you see AI changing documentation in the future?
I think there’s going to be a fundamental shift in how we create and present documentation and how people interact with it. On the consumption side, I think AI is going to help users find answers more quickly. They can ask natural language questions and get pointed to the right documentation, or get summaries that pull from multiple sources.
On the creation side, I think technical writers will still be required, either for proofing or for writing the initial content. And then it can be polished by a bot. But from what I’ve seen right now — I’ve used ChatGPT myself — it generates stuff that looks good on the surface, but when you start delving deeper, it’s like, no, right? So it’s not perfect yet. But it’s like any technology, it will get better and better and improve. I can’t predict the future, but I definitely see that it’s going to play a role.
I think there might even be more automation in the workflow itself. Maybe I’ll just speak to a bot and say, “Okay, I’m ready to push this content and merge it to main,” and it will just take care of it. Maybe bots will be performing all my reviews. We’ve got two editors on our team right now — maybe those bots will take over the editorial reviews.
So you’re more bullish on AI for consumption and recommendation, but a bit more cautious about AI creating the content itself?
Yeah, definitely. I think that technical writers will still be required. The AI can help with polishing and maybe generating first drafts, but you need that human oversight to make sure it’s accurate, appropriate for the audience, and truly high-quality. Accuracy is just too important to fully automate away.
This interview was published on 8 January 2026, and conducted as part of research for the 2025 State of Docs report.