 So, hi. I'm Lana, this is Anne. This is Talks Called Writing Enterprise Docs with an Upstream and it's about a life lesson in giving back. First of all, I wanted to start with a little story though. The Eiffel Tower was erected for the Paris World's Fair in 1889. Nobody much liked it at the time. And so, what they decided to do, because everyone hated it so much, so they're going to let it stand for 20 years. And then they're going to tear that ugly thing down. But here we are, over 100 years later since it's planned to demise and the Eiffel Tower has quite obviously become a symbol of all things Parisian and all things the city of love. What saved it in the end was the invention of radio. Basically, some smarty took one look at this massive towering grid of steel and thought, oh, look, an antenna. Like the tower in open source, we very rarely set out to achieve what we end up with. When you're working on Enterprise Docs with an Upstream, you sort of have to fit that randomness into the schedules and resources of your day job. All of a sudden, it's like trying to fit a square peg, the square peg of open source into the round hole of your day job. So when you once had a process of, you know, find something interesting and cool and go and work on that, now you sort of got this process that involves planning and metrics and deliverables and probably Gantt charts. So Gantt charts, that's definitely not what happens in my hometown, Austin, Texas. We have the Cathedral of Junk, that's what's here. People find things, they pick it up, they can actually stick it on this art installation on the east side of Austin, right? So what is open source documentation? What's an Upstream? How do we find ways to make it interesting to contributors while also at the same time ending up with something that people want to use, want to read? So this is the Cathedral versus Bazaar, the famous classic essay about open source. So if enterprise docs are the Cathedral and open source docs are the Bazaar, how do we find ways to meet users' needs anywhere somewhere in the middle? So what we want to talk about today is Upstream. Upstream is the open source documentation that's licensed in such a way that enterprises can take it, reuse it, revise it, make it better and make it good for their customers while at the same time making sure Upstream is happy as well. So today, we're going to walk through that vision as we see it. And no Gantt charts were harmed in the making of this. So yeah, I'm Anton, and I wanted to tell a little bit of my journey to Texas, which involves kind of being an enterprise writer and being a little bored in my job. I wanted to explore innovative ways of doing documentation. People were using Wikis, people were doing these really collaborative efforts, and I wanted to find out how I could be part of that. I was one of the few tech writers blogging for an enterprise software company, and I was being read by different people, even India Street analysts later told me they read my blog. I had no idea. And I wanted to learn more about the social web for documentation. So I started looking around, and in fact, one of the directors I used to work with at an enterprise documentation company said, hey, one laptop per child is trying to write a manual for the teachers and parents who are going to help children work on this little laptop. And I actually jumped at the chance. I thought, oh, this is my way to become an apprentice, to learn how open source techniques can be applied in an enterprise documentation, and I wouldn't be so bored. So that's, you know, within the year, say 2008, I had taken a week long vacation to participate in a book sprint in Austin. I had joined a community. We were able to do things that I hadn't seen before in enterprise docs. And so with that, I just started writing down as much as I could, and that's when, in 2009, I wrote a book about collaboration and community and social documentation techniques. However, Lana has taken another path. I have. I knew about Linux fairly early on. I didn't use it, of course. I was a business student, not some kind of nerd. All of which meant I didn't actually understand it. Understanding it came later. I picked up an information systems major, much to the confusion of my friends and much to the confusion still of my parents. And it was because of the information systems major. I started learning all these new and interesting things like IRC, the text messaging, a text-based chat system, the early years of Google back when it really was just research and nothing else. And, of course, open source. Some might say that my destiny was kind of set at that point. First forward a decade or so, I had gotten married. I had a daughter who's in the audience with me today. And somehow landed an office job at a tech startup in Canberra, Australia. The startup was only barely funding my MBA and my divorce. The CTO was an open source nut job. He got me really excited about tech writing. He sort of blew my mind about that. And also managed to sort of reignite this fascination with open source that I had. As far as I could tell, he actually achieved work by typing binary directly into the Linux kernel. I figured I was never going to get to that kind of level of wizardry, but I did get very proud of myself because I learnt latech out of a book and started writing useful documentation for this group. Sadly, like many startups and so many startup dreams end this way, so did mine. They missed my third paycheck in a row and I decided it was time to start looking elsewhere. I tumbled around a little bit. Obviously this time looking for a job, I had a working knowledge of open source. I had this passion for tech writing that had never known before. And I ended up at Red Hat in Brisbane, Australia. So completed a technical communication degree and rose into a management role, possibly because I'm a sucker for punishment. And then about a year ago, actually a year ago last week, I was offered a similar role at Rackspace and went and joined them. So I'm sort of here with nearly a decade now of technical writing experience in enterprise level documentation, but also having worked with an upstream, and obviously that upstream now is open stack for me. So this is a really weird world, this enterprise level with an upstream and however you fall into it, and I think we've just demonstrated you can fall into it in really different ways. It started out with this really amazing feeling that all of a sudden someone's paying you to do something that you were willing to do for free last week. And that's kind of cool, but eventually it wears off and eventually sort of have to try and work out how to justify your job. You sort of, you have competing deadlines, you have mismatched workflows, you have differences of scope in between what your work's expecting you to do in your enterprise level and what your upstream is expecting you to do. And all of a sudden everything gets very confusing, it's very easy to get muddled. So confusing that even further is sometimes you have different roles, sometimes your role at work is different to your role in your upstream with open stack. So you could just be an entry level programmer at your work, but you could be a core level contributor with open stack, or you could just be a regular person contributing patches here and there in open source, but you could be a senior manager or a senior developer in your day job. And so this obviously creates more confusion and becomes more and more difficult to reconcile those two views. So you end up with this sort of lack of time, lack of understanding, what's the vision, how do I get my day job done, and how do I not get sacked by working on open stores too much. And as the phrase and likes is to get to this planet cloud for documentation. Right. So what is the vision for open stack documentation? And it's sort of easy to put it into a three bullet slide, right? But this is the vision we want to have clarity, purpose and documentation for everyone. And if you know my work by now, you know, I have segmented documentation by users and by developers and by deployers. And so that is sort of the community needs, how do we blend these with the enterprise needs. So I think that I'm going to walk through some of the ways that I think this vision can be realized. When a person comes to open stack docs, they can actually benefit from actual open stack experts, writing from their own experiences. With the operations guide, that's what we did. If you hadn't been running open stack in production for six months or more, you were probably not on the invite list for the book sprint itself. And the experts themselves benefit from that recognition. You know, we can share the maintenance chore of a large set of documentation across different companies, providing open stack services. We can make sure that our user docs on the upstream side are good enough for anyone to link to, so that the HP cloud customers, the Rackspace cloud customers, the Rackspace private cloud customers all have a place where they're like, yes, this is truth for this cloud that I've been provided. You know, we definitely treat documentation like code. That means that we have a certain street credibility in the open stack community that we know get, we know get review, we know how to do reviews on Garo, we get to be core, we have a PTO. And that's where the cloud providers can start to have that upstream benefit of getting the recognition in the community, getting the ATC badge, getting the patches recognized as part of their contributions. And what part of the vision that I also have is that developers write for developers, users could write for users, operators write for other operators like themselves. And the really great tech writers, the really rare ones are going to have really good empathy for all of those audiences. So that's pretty awesome vision, right? Documentation for all. What does it actually look like? This is the docs landing page. And there are a lot of docs across a lot. And so the shows are wide breadth, even though it's probably kind of small print up here. But this doesn't even link to all of the contributor developer docs on each project. This doesn't even link to all of the incubating projects, say REST API documentation. There are now 20 REST API services to document. And so we are definitely drawing the lines where we have to for resourcing and figuring out new inventive ways to do this scaling across projects, while still definitely looking at what do people come to docs.obensack.org for? They come there for open stack docs. And so giving that cohesive view. We also do very big book sprints. That's what these top three are. And that's about one per year that OpenStack has been alive. The operations guide was first. The security guide was completely organized by the security team themselves. And then the latest one this past year is the architecture design guide. And again, it was we have a right. You betcha. And it's just been amazing. We actually turn the operations guide into an O'Reilly book with a custom edit by O'Reilly. And so these are some of the things that I wanted to make sure that people know the breadth, the depth, the scope, how big it is. Now down below I show online links to guides. So let's say even though we invested money up front and getting experts to write these guides, and we invested money up front for the O'Reilly custom edit, everything is still online and continuously updated and published. Because let me tell you O'Reilly is a publisher, understands the idea behind licensing where they just have one license for their print book, but we continue to maintain the ability to keep continually updating, to translate that book into many languages. That's a powerful part of OpenStorage documentation is working with partners who understand that as well. And then down here is actually the RESTful API documentation reference pages that have responsive web design that give you all the calls, that give you all the requests and responses in JSON and XML if it's so deemed by the project. There is a ton of scope here. So what are some of the motivations? Why are people contributing at all to this? So I want to say that it's because when you contribute to upstream, when you contribute to OpenStack official docs, you're going to get that recognition. I'm going to give to upstream because I know all benefit, my team will benefit, my company looks good in stack analytics, right? That's not only, it's not that you get recognition so much for some kind of point system or numbers or patches, it's that you get recognition that you know your stuff and your company knows your stuff and they're willing to support you in that endeavor. There's also reciprocity. I'm going to give it to upstream because I know I'll benefit. I'll write the section on upgrades because someone else is going to keep maintaining that install guide that I'll be able to go to over and over again as the release keeps going. I want to talk to the upstream team. I want to influence what's written in upstream and then that will be useful to us. So it's a give and take, a give back, a take back. As an example, Cisco contacted me recently and they're going to use the security guide as a basis for their security documentation for OpenStack. That's a huge win. That shows us we did something right and they're going to be able to give back what's a new update to upstream. And I'm pretty sure Red Hat takes like user docs and they can completely rebrand them as their own because the licensing allows for this. And I want to make sure people know that you can actually do this. We license everything with a license that enables reuse as long as you give attribution. Another motivation, efficiency. So we do a lot of reuse of documentation. The common chapters are written once and used in a bunch of different places. We can talk about how you get community support over and over. We actually have a shared glossary. I don't even know how many terms are in it by now, but it's 20,000 lines easily that we can share across all of these. So it's one place to maintain. And the thing is that glossary came from assisted men in Iowa who sat down and wrote an entire wiki page of OpenStack glossary items. And we've been adding to it ever since. And then the sense of community. So I love this because OpenStack is people. And I don't know if you guys have heard that before, but it's that sense that if I write community docs, that is OpenStack. OpenStack isn't throw something over the wall and they're going to take care of it. OpenStack is the people that you can come up and talk to at the summit and say, Hey, I've got a question about this. Can you help me with it? And they are going to help and they're going to get it into the upstream documentation. And then lastly, or not lastly, one more, but efficacy. And I love this word because I'm a word nerd, but efficacy is that I have influence in the docs because I work on the docs and I have influence in the community because I work on them as if they're code. So a doc writer has just as much efficiency, just as much street credibility as any developer in the OpenStack community. Now, that is going to go through. Well, and I want to say that the sense of efficacy is that we feel part of the community as well. So that's kind of my last point about upstream docs is it's very important that we belong. We're treated just like all the other ATC years were at the domain summit. We're at the we're at the design summit. We're at the summit all the time. And let us going to walk through. OK, so that's the vision. It sounds very nice, doesn't it? Well, let us going to walk through some of the practical advice for actually dealing with this very strange world of open source open source documentation. So like many lists of hints and tips, this one starts with the obvious, which is get organized. I don't think I've seen a list of hints and tips that doesn't start with get organized. I'm also going to put a disclaimer up here and just because I tell you to do these things doesn't mean I necessarily do them myself. So we're all fallible. But yeah, this one's get organized. So as soon as you as soon as you know your enterprise release dates, make sure you let your upstream community know. Soon as you know the open stack release dates, which usually are fairly predictable, make sure you let your enterprise know that you might not be around for a couple of weeks and you might not be as able or as visible during that time. Obviously you won't always have control over release schedules, but if you do possibly in your enterprise then maybe it can be a good idea to actually step those releases out. I know in Rackspace Private Cloud what we actually do is try and step those about six weeks out from an open stack release, we step ours out. So it means that you get this nice cadence happening. Obviously always prioritize your time, pick your battles. Don't spend three days trying to nurse a patch through, especially if it's trivial, trying to nurse a patch through the review process or arguing over a minor technical point on a mailing list, especially if you don't have to. If you're lucky enough to be in a management or a senior community position you can actually outsource some of that stuff to assign a proxy to attend some of the more regular or non-essential meetings or to monitor mailing lists and give you a heads up if something happens. Obviously not everyone has that luxury. And finally on this point don't fall into the trap of doing enterprise work while you're at work and doing your upstream work while you're at home. We all do it. We all go home, I'll just check on that patch or I'll just do a quick review because I didn't get one in today. It's a recipe for burnout. We've all been there. Regardless of how much you enjoy doing the community stuff and how much you are totally willing to do it on your own time, it's actually really important for you to have time with your friends and family as well, to have time away from the screen to make sure you hit the gym occasionally. And of course my favourite time of the day is couch time. You've got to make sure you have some couch time too. My second piece of advice is about community and how to be a good community member without looking like a company shill and actually being able to keep your job. So you don't want to look, you don't want to be that guy on your open source mailing list who's always telling everyone, oh well it should be like this and everyone knows you're just saying that because that's what's going to make your job easier. But at the same time, you don't want to lose your job by working actively against your own enterprise either. I think possibly the easiest and the best way to handle this is to be able to foster a sense of culture and inclusion and honesty and respect. That's not always easy. You're not always in on the ground floor with things like that. However, you can foster your own your your own image even if you can't affect the community. If you're acting in an honest and open way, then the people around you will be more likely to act in an open and honest way because they recognise you as being open and honest in the first place. Obviously, yeah, create your own reputation even if you can't create the reputation of the group around you and hopefully you can bring the level up. Oh, the final point I wanted to make on that slide was that if they're, you know, if you've got a customer asking for a feature and so you are trying to push a feature into upstream, then make sure you let upstream know that it's for a customer because quite often there's a really useful use case that you can you can have there. So you can actually turn and go, well, you don't have to reveal who the customer is obviously because there is a use case of company X. Maybe we should address this as a possibility for upstream. If you're trying to push a feature because work wants you to do it and you don't have a customer for it, then maybe it's time to go back to your work and find out why we actually after this feature and see if there is a use case there that you can present to your upstream community. You know, don't just push features because you've also told you to, basically. This one's about goals. How do I justify my existence when sometimes I spend days arguing on a mailing list instead of landing code? I think we've all done that. No, I have. You get so caught up in an argument on a mailing list and the term is bike shedding. Does everyone know what bike shedding is? Yep. So, yeah, the term is bike shedding. You don't want to spend, you know, a week arguing about the colour of the bike shed on a mailing list when you really could be getting on with something more important. It's red. Just kidding. It's a really good idea to have yeah, have your upstream responsibilities enshrined in your job description. That's something I've been quite careful about over the last few years as well, is when you go to your boss and you're doing, say, your quarterly reviews or when you're negotiating for a job in the first place, make sure your upstream job description is actually listed in there as part of what you do. And also make sure it's a performance goal. So your performance goal can be things like so many lines of code or so many patches or it could be more general things, like achieving a higher status in your community. So you may be an ATC now, but maybe you want to achieve core or something like that. So you can you can enshrine those goals into your workplace as well. Make sure that your boss knows about it. And also, you know, you've got to make sure you do it rather than just talk about it. So make sure you actually are active in your community and that you're telling your boss that you're active in your community so that they're aware of it. Reuse. How do I get stuff in enterprise? I'm going to start that again. How do I get the stuff in enterprise into upstream and back again? And the prereq there is without losing my mind. Just in case you can't read the little little letters down there. Obviously, this is going to be different with every project and every community. The main thing to do is to create a system. And this could be really, really simple. It could just be writing things down on a piece of paper beside your keyboard as you as you come across features that you want to pull back down into enterprise or if you want to push back up into upstream, just write it down, cross it off when it's done. It can be that simple. It's also really easily achievable with something like a Kanban board. If you're doing any kind of agile Kanban board, which can just be sticky notes on a wall, you know, to do, doing and done. Or it could be that there are heaps of tools available and I know within Rackspace for your Trello quite a lot and that can be good for a distributed team so that everyone can access the same the same thing. It's also really important to be realistic. Don't just take things upstream or bring them back down because you wrote them and you think they're cool. I mean, that's great that you think they're cool, but make sure that there is actually a use case for them and that goes back to the point I was saying about before. If you do have a customer after something, make sure you use that use case to justify bringing it up or down. And also, of course, the obvious caveat there is don't be all give and no take or all take and no give. You don't want to be that guy. Finally, does everyone know what yak shaving is? Has everyone shaved a yak at some point in their open-source career? Excellent. So yak shaving is when you start off doing one thing and in order to do that thing, you need to do some other thing. And it turns out that you're missing a piece for that thing. So you've got to go off and find some other thing and solve that problem. Eventually, three weeks later you come back to the original problem and realize that's not the problem anymore. That's yak shaving. And I found this delightful picture. It's actually from a French children's alphabet book. I'm not sure from when, but I'm guessing possibly 20s. So there's a lot of yak shaving involved in enterprise and upstream. And I think it's really important that, you know, we're not all plugged mentally into the internet of things yet. And I'm sure that'll happen at some point. But until then, this is going to be a difficult problem to solve. We're going to have to continue the yak shaving for some time. Every community, every organization is different. Sometimes they're radically so. Sometimes it's kind of like picking two random cogs or two random gears and trying to get them to move together. Sometimes you just get a massive jamming of gears and it's never going to happen. Sometimes it'll kind of half work, and sometimes they'll fit really, really neatly. But the grand majority will kind of half work. And that's, you know, sometimes you've just got to deal with what you've got. It's really important that you align your enterprise and your upstream activities as much as humanly can, but we do recognize that it's not always possible to get them complete. Oh, I've lost my point of thought. Don't yak shave. Sorry? You were just yak shaving yourself. I was yak shaving. I went off down the garden path. So obviously even a company that just decided to work on open source last Wednesday, they can still be a good open source citizen. There's nothing wrong with that. And obviously the more people we have working on upstream all the time is going to be better. The more the merrier, right? Obviously, the more that you can align those two components to your upstream and your enterprise will be great. So make sure that if your company's hiring, you let your upstream community know. Make sure, you know, if there's someone in your upstream community who thinks it's absolutely amazing, let your boss know and say, is there something we could do to hire these guys? He's really cool. And so hopefully you can just be not the one guy who's working on upstream. You can have a bit of give and take as well. Oh, and can I interject? Sure. Sorry, we did not even rehearse this, but if you're doing open stack developers, say 50 of them, I want you to hire five open stack upstream writers or people who were at least work 50-50 on the docs that your team needs of those developers doing open stackish things, and the upstream docs as well. 10% is a pretty known software documentation correlation ratio for developer to writer. Absolutely. My second that. And my final point was sometimes you do feel like you're working to full-time jobs. Sometimes you sort of feel like in one of your jobs you're fighting fires and in the other job you're saving drowning kittens or pulling them out of burning buildings or something like that. Yes, we all have days like that. You know, obviously if you get to that point take a holiday, have some time off, but please come back. The open source community can't afford to lose brilliant people who can do both. Yeah, don't give up. The open source world needs you. I think that. I think that's it. We can take questions as well. Questions. There is a mic, but we'll just repeat them for the recording so don't feel like you have to go. I gave a full three minutes to wait for questions this morning. I can wait. No, it only felt like that. Stunt them into silence. I know I'm getting questions all over the place out there, so feel free to ask now. Go for it. So the question is how much time of your jobs do you spend on upstream? I'll let Lana answer that first. The answer for me at the moment is actually quite little. I've grown a documentation team very, very quickly. I'm actually giving a talk about that in January in New Zealand if you're interested. We hired eight writers in eight months, so I'm busy managing that group. At the moment I do try to get at least a code review every day. At the moment that hasn't been happening much, but at the moment my upstream contribution is very small. And that's something that I was intending to mention that I think I skipped over earlier too is if you are busy with releases or busy with enterprise stuff, try and sit down and even if it's just over your morning coffee, do a quick review or two, make sure you do do something every day. That's something I do try to do very, very hard and I don't always succeed with travel schedules and things. But yeah, I mean if it's just a code review I'm checking mailing lists. And Rackspace hired me in September 2010 specifically to work on OpenStack documentation. So me and a community manager were the first two hires for OpenStack at Rackspace. I work 100% on upstream, but I have in the last year been really, really interested in developer documentation and working on a developer experience team. So they actually asked for 20% Rackspace time. And I'm trying to find it a very interesting space for me. And I think it also enhances my upstream work as well. So that's where I'm at right now. It probably really started at 100% and it's about 80. And I actually have a calendar item at 8 in the morning to review OpenStack docs because I can get my day can get away for me in meetings and yeah. So I actually have to schedule it for reviews specifically. Ideally for my team I would like them to be doing 50-50. That ebbs and flows with release cycles and that kind of thing. We just had a major release for Rackspace Private Clown which meant all eyes and all hands were on deck for the release. But then in the quiet time the week or two after that well we're just sort of waiting for the dust to settle. Everyone goes back to pretty much 100% open source. So it varies a lot. I think if you take it in total on average I think 50-50 would be a nice place to be. Lovely. Anyone else? We can do a dance. That's going to be enshrined on the internet forever now. Keep doing these things. Well, let's take a minute. If you work on Opensack Docs and have landed a patch in the last release stand up because let's recognize you working on upstream right here now. Stand up. Yeah. Yay. Go the Docs people. Yay. Thanks for doing that. So everyone else in the room who didn't just stand up your goal for the next summit is to land a documentation patch. We'll help you. We will help you. Email me personally and I will help step you through that process. Find us on IRC. We're always willing to help. 195 individual Doc contributors in the last six months. And four of them came to our talk. Wasn't that nice? Anything else? I think we might wrap it up. Thanks for coming everybody. Thanks everyone.