Documentation, Disrupted: How Two Technical Writers Changed Google Engineering Culture



cool hi I'm marina McNamara I'm a staff writer at Google been there about eight years but last year was my first time at write the Docs and actually what a year it has been it has actually been the best year of my career which has been a long one it's been about 20 years in tech writing and it is actually being almost one of the best years of my life and in terms of what we've done and accomplished and built a team around the area of internal documentation at Google and it all started here to write the docs so I want to give you a tiny little bit of background where we did and one of the things you probably can't see that very well because it's a really old photo but it's my company directory photo it's my first communion you see the dirt road and the Atlantic and stuff but one of the things I really like about conferences like this and meeting with other technical writers is that we tend to come from a really diverse set of backgrounds and my own path to tech was not a direct one so I started off I studied English because I wanted to write the great Irish novel this was going to be my ambition and my graduation it became very clear that that was not going to happen so instead I said I will go to law school because I'm going to be the people's hero and by the end of Law School it was clear that that wasn't going to happen either so I have to kind of change my plans though instead I decided I would go to the London and join the glamorous work of literary publishing where I would maybe discover the great Irish novel and maybe nurse it in takes distance and maybe attend all these parties with salmon Rushdie and everything like that it was going to be awesome but instead what happened was I actually ended up at virgin publishing the book publishing arm of virgin and instead of the great Irish novel I worked on books about Doctor Who books about erotic fiction and about serial killers so I've forgotten more about these things than you will ever know this it was suspect a lot of time doing this and then I went to other general publishing houses like I was at Random House for a while and then I went to Dublin to be managing editor of a suppress which was a very small feminist publishing house that had a lot of impact on the women's movement but none of this was related to tech except I started freelancing and it's estranged the paths your life takes that ends up that you're standing in the stage with a sprung dancefloor important and I took it britches awesome and I took a two-week contract long long time ago at Microsoft in Dublin and I was editing content Frank art world atlas and that to each contracting this completely unfamiliar environment it ended up I ended up joining Microsoft ended up being international editor for Encarta and a card world atlas and then in 98 I moved to Redmond so that was the beginning of tech writing career so altogether I was in Microsoft about ten years and then I was in Amazon for about eighteen months and now I've been at Google for about eight eight years that's the kind of tech writing background and I wouldn't be anywhere else this is I really loved my job one of the things I'm actually one of those intolerable morning people I am intolerable even before coffee and I and um advance from my bed I can't wait to get to work I can't wait to open my laptop I can't wait to get online and I love it but this time last year this is not the way it was I've got to say that this time last year I was feeling reburn doubt I've been there I've been working a long time I'd be feeling like am I making a difference am I making an impact and I started reading a lot about happiness at work and this is a TED talk that I really recommend and he talks about the happy secret to better work and one of the things he talks about is that we've all been kind of brought up to think the work harder and happiness will be your reward you know happiness is what you get when you work hard and you do this but he says no that's not the case at all actually what it is is that we work better when we're happy happiness comes first and when we're happy we're more creative we're more connected we are more productive we can actually have you know doctors apparently or 31% faster to make a correct diagnosis when they are happy so imagine for technical writers and he says there are three predictors of happiness in your job and they are optimism your perception of stress and then connection to other people and optimism he defines as the certainty that you will make a difference your work is having impact and it matters and it makes a difference and also that it's being recognized and acknowledged and I think that's important we all work all the time and we need to have this difference in context about the challenges that we face in Google and I think it's familiar to anyone who works in internal engineering documentation it's just we have it in a huge scale um with twenty three thousand engineers we've hardly any technical writers internally the ones we have are amazing they do amazing work but the reality is that most engineers write and maintain their own documentation and this is in an ecosystem of literally thousands of constantly shifting interdependent systems the people are working on and another thing that is really important to know about Google culture it's a great thing about Google culture but it can make things challenging nobody can tell Google engineers what to do really and truly there are also they can pick their own systems they can pick their own tools there's a lot of tools available everybody has a lot of different ways of doing things and everybody has super strong opinions about which one is the best I've already been told that this is wrong and I need to fix this slide this is what you end up with though when you're in documentation it's totally what you end up with it's the way the thing we had documentation was in Google Sites wasn't dark citizen a wiki it was an HTML pages and here we have you have here there's no documentation at all or there's some documentation but it's not really reliable and I'm a fall apart at any time and you you don't know if that's been sitting on the floors that trustworthy you know that's the situation we were in so I was not feeling optimistic at that time because what we had learned we'd tried lots of different approaches to getting this information and clearly top-down doesn't work but we had also found that bottom-up doesn't scale we had to had worked on this thing where we we would work with teams to make their content exemplars and we hoped everybody else would learn from that and but what happened is we leave and the site the documentation will fall apart again and you know people wouldn't maintain it so much the second one is about your perception of stress and it's actually not about stress itself stress itself is not necessarily bad what's bad about stress it's do you perceive it as a challenge which is a very positive energizing thing or do you perceive it as a threat and I was like super threatened because I could feel like there was this challenge Google has this survey every year internal survey that they take incredibly seriously and they ask hundreds of questions about people's well-being and their issues at work and what makes them happy and what makes them productive two years in a row the single biggest hitch for engineering productivity was the lack of available easily findable documentation that they needed to do their work internally so we're awesome at organizing the world's information and making it universally accepted it's a little harder to do internally and in addition and this is personal I'd recently been promoted and I was like yes now I can kick back maybe coast a little but actually what did happen was my part impostor syndrome just came out both swinging and now the stakes were going to be so much higher and my public shaming was going to be so much greater because of this so this is my state and the third thing that is really important for happiness at work is the idea of connection you're connected to the people you work with you're connected to the work that you do and you have some influence over the directions you take and again it's not just Google I've seen this at other companies I think that one of the things that is common in our profession is that we're not always we were doing more better jobs but there is sometimes a scarce a culture of scarcity around access to engineers engineering time and particularly at the high level around engineering leadership you know director you know where we want to be the direction we want to go and the result is that you can sometimes feel kind of isolated you know that it's it's hard to make a difference so that was my frame of mind this time last year not doing so well in any of these and then I went to write the dogs and it was fantastic and it was my first time at this conference and there are a couple of these are a couple of talks that really jumped out at me but mostly was the whole kind of getting everybody together it was connection but these two talks were really interesting especially this one about Twitter because I was frantically I am I co-workers like they have the exact same problems as us if the exact same and they figured out a way they are putting the dots with the code you know it's really good and we should think about doing that and then this ideas of minimal Viable documentation and these were really big takeaways for me couldn't wait to go home this is my coworker Aaron who's in the New York office and we were both kind of in between projects so we started kicking this idea around and the first thing we did was well let's talk to as many engineers as we can because we wanted we were writers but it seemed to us that the problem was engineers engineers had to know they have to write the documents it was like the problem that we had was all the solutions we designed before were designed for writers when actually for this internal engineering ecosystem writers were not the users mostly you know they could handle all of these tools it was engineers who are the users and we heard the same thing over and over again it's confidence in Docs is very low they either don't exist or they're hard to find and when you do find them you don't even know if they're reliable or they're wrong and when we asked why do you think this is it was like what we don't have time to write dogs or do i prioritize dogs over implementing this new feature you know how is that going to ding me at performance time there was just no culture of dogs being truly integrated into the engineering workflow and when we tried to go deeper for the very root cause of that it was really that we have almost I think it's one of the biggest code bases in the world integrated it's enormous and 23,000 Engineers pretty much working in it but the problem is here's our code base and the model is your code is in this wonderful code base and your dogs are anywhere at all your dogs can be over here and a site they can be on a wiki they can made a post-it note on your table and what we realized was the documentation will never be part of engineering culture and she was fully integrated not only into the code base but also into the engineering work flow but we also had this idea that okay what if we figured out a way to do this but we really really did not want was to create another competing content management system that would just add to the fragmentation of documentation so right from the very beginning when it was just Aaron and me like in the week or so I have to write the docs we're saying we're going to go all out because we have nothing to lose so we can just start small and we want to design a system that can become the standard for all of these 23,000 engineer's working in the code base we were going to go big or go home and we were inspired by this onion story five blades was actually our codename and we said we were going to go full on five blades on this problem so what does five blades look like we're going to end enable all engineers to create and maintain and find their documentation using their existing tool sets and do it in simple format like markdown which is portable and we would render it as a a nice predictable URL suit good readers and source are you created in the URL but we had one problem which is that our server could not actually read or render content out of the code base which is a problem and then we thought again we've nothing to lose so why don't we just ask so we sent a mail to Steve who is the awesome engineer who runs this over in Munich and we asked okay hey you can't do this can you do it why not and I love the time difference I'm on the west coast even of Munich came and worked the next day Steve had written a design doc he had set up a security review the system was basically he said yes this is how we can do it and then over the next nine days we my greatest we found someone to my break the documentation we did a proof of concept this is obviously its internal documentation of this obviously placeholder but you can see that this is a very simple rendering of markdown it's not ideal you can see that we're having to link to a stylesheet and stuff like this but it was a proof of concept we could render content out of the codebase and so G 3 dot that's the name of our project was born and the idea we're all about branding this is our branding it's just the terminal it's nothing you don't need radically simple it's you just drop in markdown and it just works so on July 8th we launched our first full-on website which is for a major internal infrastructure project that is not called Wolf Hall and and you can see that it looks so much better you can see that we have some navigation in there this page info that is read directly from the code base with some navigation we get some nice code formatting all of that kind of stuff and this is hipster Laura a hipster or something I don't yeah which I found that I'm about to write the talks last year and you can see that the source for this is actually really simple it's just you've got your list you got your sample code you have a dynamic TOC and all the navigation it's just a bulleted list in markdown if the server finds a name called a file called sitemap dot MD it'll render your navigation like that so you get it all for free it's really easy to do and the reaction was really great the accurate reaction was incredibly positive from engineers like this the best thing ever this this is my favorite quote because I had never heard an engineer say this in real life I had never heard an engineer safe so what happened then was it was mostly engineers over the next couple of weeks we ended up having about 18 projects my greatest and the really cool thing was we only talked to about three of them most of it spread virally from engineer to engineer and that was the way we thought it had to go because nobody tells them what to do and you know it had to come from other engineers but there are also some tech writers who are really facing a lot of problems at scale so that's Edie who works in search infrastructure and Ricardo nods and Theodore who is actually here today and who had this monumental task here here's a team of 300 developers with scores of projects managed their documentation right harder right faster and obviously that was not going to work but what was really cool about this was these writers so this had potential it didn't have fish all their needs so in a very open source way governance belongs reproduce they actually just joined the team and they started building the platform and building it out what was also really important and really key to success was even though everybody at the stage here except with Steve is a writer never lost the focus that we are actually dealing with engineers and that was our mantra we are focused on the user relentlessly to do this oh I click it there so we talked a lot about the teams we wanted everybody to be happy and we want everybody to be productive so we actually did at this stage think a lot about the type of team we wanted to have and it was very we talked a lot about this and we really want to be a place where we moved fast so we had a policy of no cookie licking you know cookie licking is it's like when you there's a feature you think is really cool and you would like to do it but you don't at the time so you lick the cookie and you put it there so no one else can take it and we're saying that is not gonna happen we we are focused on momentum and growth and no cookie licking we want everybody to have an opportunity for impact and governance belongs contributors the next stage that we had to do after that though we saw adoption growing people loved us but it was like how do we get this really into engineering culture and the other thing that was really key for our growth was that we integrated into the core developer toolset as Google we started forming partnerships with the developer infrastructure team and so the three main tools that engineers used to find and edit and preview and wrote do code reviews all of those had were integrated with our documentation platform and with the server's so you could instantly view a rendered file you could do all of this and this was really key and one of the things that we found was the integrations did not have to be big even just one tiny little preview this file made a huge difference in usability so that's a tool chain so adoption September 818 projects December we had almost 160 and again most of these were in completely viral and we were feeling awesome about this so we set some really aggressive goals for q1 we said we want 300 projects up and running in q1 the while this was happening we also found that our rules were changing and we talked a little bit about connection and scarcity all of a sudden engineers and engineering managers and some kind of very quite high level engineers they started reaching out to us they're saying this is that how can we help would you like some money do you need some swag can we you know what can we do can I lend my voice to this can I support it and it was if this was almost the most awesome thing because we had a seat at the table and it was we were really able to come to some of these meetings as peers with these engineers in a way that we hadn't really had before and it was really exciting time to be there so this is our adoption you can see back here I think it has like that's one team one contributor this morning the very first thing I do when I wake up this I check adoption and we are at about 1,600 projects right now our aggressive okay r4q one was to have 300 projects we have 930 and all of this was spreading virally from engineer to engineer people were seeing they were talking to each other about it and that's how it happened and that also meant we had to really look at our team we are no longer this kind of guerilla team those operating under the radar kind of scrappy startup for you now on the way to becoming a core part of infrastructure so we had to kind of change our goals always keeping the big five blades goal in mind but the the objectives we now had to figure out how to have a stable reliable platform how to make it the most useful platform for engineering at Google and we also had to go like an open yard g3 dock team is best team this is team where you can come and do your best work and you can be really productive and you can have an impact and that will be recognized and Archean grew and grew this is this is the best team so you can see that we have roots and my color senior and level engineers who came in and started really kicking ass and building out the platform with new writers and people are helping out and the core thing is that this is my job and theodor an errand or 50% but everybody else who's building this platform is doing it on 20% time as a volunteer that's they're doing it because we all have the same goals and objectives and we're driving towards it and it's really great so what we learn how we're doing this these are the things we know are true really and truly we think this is what we learned from this process you have to focus on the engineer in the internal engineering thing space where engineers are responsible for the docs what you have to take off her writing you had we have to think about we couldn't develop tools and expect engineers to adapt their workflow in two hours we had to look at their workflow and adapt it into theirs focus on the user the writers if it's a useful platform the writers will follow but again if focus on the engineer second thing and this was released the cookie licking the stronger he came out – cookie licking was momentum matters do it small just small basic platform first to have a rock solid to have a very reliable and then add our features as they get good and the user is delighted you know we get a lot of really positive feedback every time we add on a new feature but it was start small iterate often get it out there the single biggest thing that we learned and this is really fundamental to our perceived roles technical writers on the team a lot of us had had a ton of experience like Aaron was a very senior tech writer at IBM I've been there for 20 years there'd been you know there's a lot of things and it was like we have all this expertise and yet nobody is respecting my authority nobody is coming to me and saying can you please help us fix our Docs tell us what to do and it dawned on us that after a while that's all our experience in the tech writing world and our experience in tech in general and our knowledge of layout and CSS and content chunking and organization it was exactly as relevant as my time working on Doctor Who it was not relevant at all viciously nobody was going to come and ask us to give them direction on things but what we found is that when we did step up and focus on the engineer we did develop Authority and we did develop influence and it is there for the taking if we do that it was the best so quick happiness review and where we're at on all of these things first one is optimism do you make a difference it does make a difference 1,600 projects are using it but even more there are thousands of change lists there's hundreds of a submissions every day we're now engineers they changed the code and they update the docs in the same change list that is crucial for maintaining Doc's and that's the part of engineering culture it is beginning to be part of the workflow and the integration the perception stress I have to say I actually do work more than I have worked ever and I don't think that's a good role model it's marathon not a sprint but I'm also less stressed than I've ever been it's like I I can't wait to get work I want to lovey-lovey work you know and it's but and it's a little stressful because we have an environment and a team that's really motivated and self-directed and amazing people and we can see that we're making a difference and the third one is connection and there's two types of connection and the first is connection to the team I mean it really has been a satisfying experience to work with this team g3 top team is best team but the other one was connection to engineering in general and to the goals of Google and this was really a change for us and I want to tell a story that illustrates this little pile of guys in New York visiting Arin and there's something we wanted to do with g3 dock we wanted to connect it to some other kinds of information and Erin and I to individual contributors tech writers so pretty far down on the ladder we call this meeting and through a bunch of very senior engineers there and we were sitting there and discussing this feature and one of the engineers said hmm you know this is going to require a changed the whole way we do across the codebase and the other guy the most senior guy in the room leaned back and he said well you know three of the five people in this room are Global approvers of the database I do not think that is going to be a problem and then my phone bleep beat and I looked over an area I was sitting there very quietly it's very hard to tell what Aaron's thinking but my phone blinked I got a text message and it was early and it is so the message authority and influence they're there they're ours for the taking if we focus on the user and step up and solve the engineer's problem that's it it really is it's been the best year if I could say anything I would say go five grades be happy

6 thoughts on “Documentation, Disrupted: How Two Technical Writers Changed Google Engineering Culture

  1. A lot more time is spent talking on how great this new process is than on what exactly it is.

  2. Great presentation. How could you bottle this and spread it to smaller companies

  3. Cool video – would be sweet if they had high-def versions for readability of the slides, etc.

Leave a Reply

Your email address will not be published. Required fields are marked *