Internal developer docs


Last year and this, presenters talked about developing a culture of internal developer docs. Their talks were inspiring. Do other folks have stories to tell about similar efforts? Or lack thereof and lamentations therefore?

I’m one of a group of four writers at my company trying to get more visibility – and more resources – for internal dev docs. A few projects are pushing hard from the engineering side for writer resources, but there’s also resistance on the part of both upper management and some (other) engineering teams. So our situation is pretty ad hoc and project-dependent. We’re planning to discuss the situation formally at an upcoming internal gabfest.

What can y’all tell us about how dev docs are managed in your situation? Are writers involved? If yes, how many? Are devs required to write docs? Anything else at all? We’re looking for inspiration! (and yes, we know the Twitter and Google stories, at least as they’ve been presented at WTD …)

(And if y’all want to see a bit of what one of our teams is doing, I describe it a bit in the topic about API Documentation Generation Workflows)



Yes, we have successfully cultivated the developer docs culture at our organization.

I was the sole Engineering Technical Writer at my organization. In a span of an year, I created the onboarding program for new joinees - which gave them an insight into the product from the user’s perspective, and then led them behind the scenes to understand how it actually worked at a technology level. Then I developed the architecture docs - the foundational documents that explained the core technical architecture of the product that was fairly stable. And then I developed the design docs - these were release-specific docs that changed pretty often. Along with this, I created a technical knowledge base that non-engineering folks could refer to - it helped them learn the language and jargon of the engineers and thus communicate with them effectively. And I created a writing program for developers that would enable them to write design docs on their own.

The project succeeded mainly because it was our CTO’s initiative, and the Engineering Director, who also was my direct manager, supported it whole-heartedly. Getting the buy-in of the developers took time, but once I demonstrated how internal tech docs made their lives easier, they were onboard relatively quickly. It was due to this complete buy-in that I could produce my best work so far.

I have written about it on my blog as a part of my writing portfolio for my graduate school application:

Hope it helps :smile: