I know I often say nice things about the guests on this podcast–because they routinely blow me away with their technical acumen and genuine enthusiasm–but really, there aren’t enough nice words in the dictionary to adequately express my fondness for Anne Gentle. She’s been an exceptional contributor to OpenStack as the project team lead for documentation, plus she serves as the OpenStack Documentation Technical Lead at Rackspace. And she’s a mom. And she spends her spare moments helping both women and school-age children find a passion for technology and a pathway to a career in the industry.
Bam.
Can you see why I like her?
In last week’s podcast we talked to Anne about a wide variety of OpenStack- and open source-related subjects, including:
- How quilting got her into technology
- How she gets elementary school kids (and their teachers) excited about network topology design
- Why she loves doing OpenStack documentation
- How a “book sprint” works
- Which audiences she’d like the foundation to write guides for next
- Why her team is transitioning from Docbooks to RST
- What the Night Scout Foundation is doing to help kids manage diabetes
You can follow Anne on Twitter at @annegentle and find her OpenStack sessions here.
Jeff and I are headed to Vancouver! Check out Jeff’s sessions, my sessions, and follow @openstackpod to catch the Summit Minicasts of OSPod.
See past episodes, subscribe, or view the upcoming schedule on the OSPod website.
For a full transcript of this podcast, click “Read more,” below
Niki Acosta: And we are live! Good afternoon, good morning, goodnight, whenever you may be watching. I am Niki Acosta from Cisco and I am so, so, so, so happy, because we have Anne Gentle from Rackspace here with us today. Anne and I go way back from the early days of Rackspace, she has been a mentor to me, a great friend to me, we have had many a great lunches, and so I am just so thrilled to have you on the show today. Hi, Anne!
Anne Gentle: Hi, Niki! Thanks for having me, I am super excited to get to chat with you.
Niki Acosta: And you are currently also in Austin, right, today?
Anne Gentle: Yes. Awesome Austin. I am actually right off of I-35, or ‘Main Vein’, and I hope that truck sound does not come through.
Niki Acosta: If it does that is okay, at some point my dog will bark during this thing, it is like guaranteed.
Anne Gentle: That will work.
Niki Acosta: Yes, for sure. So, in addition to being a part of Rackspace, you are a technical contributor, documentation lead for OpenStack.
Anne Gentle: Yes. I was one of the first hires specific to OpenStack, at Rackspace. Me and a community manager, yay! I have been around since just after it was announced at OSCON in 2010. I started about September 2010. I still remember going to this coffee shop in North Austin, so I could meet up with Jim Curry and Mark Collier, I had to make sure that I saw the Rackspace Austin office, I do not know why that was a big deal, but I wanted to see it because I could not find it in Google Maps. It was like some super secret place, that I just had to know.
Niki Acosta: Uh-oh, we are dropping the broadcast a little bit.
Anne Gentle: Okay. Okay.
Niki Acosta: Thank you Rackspace WiFi, right?
Anne Gentle: No, mine is on a wired hopefully it is okay.
Niki Acosta: Okay, so we will start over. Take us back, how did you start in tech, tell us about that journey, and recap where you just were, because I do not think I caught the tail end of that.
Anne Gentle: Okay. Basically, one of the first hires at Rackspace for OpenStack, after Open Sourcing it. The way I got into tech, I think is something that is common to a lot of women in tech that I have talked to; my dad is an engineer, and he brought home all kinds of interesting things, technology in our house was: computers. It was these large plotters with markers that drew things in our living room. Literally, my dad would bring it home to show us, and my mom is a writer and a quilter, they actually have a really fancy programmable sewing machine. In our house technology was just integral to a lot of things.
I think that a lot of people of my age, generation, would have you … “Well, my first computer was a such-and-so.” I find that a guy thing, like for women, I feel like sometimes they will start off with, “Oh yeah, I saw this great talk in Austin, where, um, this woman said that her first introduction to, um, the web and technology was making HTML and CSS for, like, NeoPets.” I always feel there is this second story from women and tech, about how they got started, that may be more web-based or creativity-based; quilting, how odd is that, to be a way to get started with? I didn’t hear that last one?
Niki Acosta: We are breaking up pretty bad here, let me …
Anne Gentle: Oh, I can hear you, no.
Niki Acosta: You can hear me, your photo is getting a little grainy and you are dropping … Mr. Porter DeLeon, you are watching live, if you could pop in the chat if you are seeing the same issue on your side that would be incredibly helpful. Just pop it into the Q&A, and let me know if you are seeing a drop on your end. If you are, we may be able to restart here.
Anne Gentle: Okay. Let me know, I just … [crosstalk 00:04:53]
Niki Acosta: Oh, now you look at lot better.
Anne Gentle: Is that better?
Niki Acosta: Yes. You look a lot clearer and sound a lot clearer.
Anne Gentle: Okay. I am going to do that, I am going to take over some big wires.
Niki Acosta: Yes.
Anne Gentle: Better?
Niki Acosta: Yes, so far so good. Thank you technology, this is what we get for doing this live. Good times. I am sure all of my subscribers when they get this are going to be like, “What?”
Anne Gentle: Hey man, live is the way.
Niki Acosta: Okay. Programmable sewing machines, a lot of cool stuff. You do a lot for, I remember like every time I turned around it sounded like you were going to workshops to teach girls something, or you are doing something with your boys, that had to do with coding and programming. I do not know how you tend to make time for it all, but you have this really cool exercise that you do with kids to teach them. I want you to tell us about that, because I think Jessica Murillo, who has also been on the show, you just sent that idea to her, for her to do a workshop. Can you tell us about that exercise that you do?
Anne Gentle: Yes, even in describing this I realized I have done this with school children from grade 3, so elementary, all the way up to college students. What we do is a cloud simulation and so you have a bunch of small objects, a squishy ball works well, and a bunch of buckets. You can actually do these iterations on ‘design me a better cloud,’ or ‘design me a better network topology’ is what it really ends up being. You ask the students questions and make it very inquiry-based, so that they are trying to figure out, well what is more efficient? The rules might be: it has to touch every person who is going to be a cloud server, they have to use five servers to begin. One of the rules is you have to pass it across instead of side-to-side in a circle, that they end up making a star topology, and you get into all of these things, like: what if packets are dropping, the balls are dropping, what can you do, can you error correct, can you add another server whose only job is to pick up the ones that fell?
These kids, the best part of presenting it out of my elementary school the other day was, the teachers were lining up to watch the kids do this. They really got into it. I also took, we were outside which is another great thing, you are standing up, you are active; the very last transport system you do is every kid in the room. I have done it with 60 kids, all in a row, and they form this shoelace train of moving these balls through this system, and it is amazing. The teachers wanted to see pictures of a data center, they wanted to see what the cables look like, I would show them cooling systems. It was really interactive and really fun.
Niki Acosta: That has to be really fun for a kid, because they probably, by that point any kind of wheel training they conceptually grasp something … it is weird. My son is almost 5, and he is into this game called “Blocksworld,” which is kind of like Minecraft except you can kind of program all the pieces. I have never taught him anything about it, it was probably one of those commercials that popped up that said, “Oh, you’ll love this game!” I was, “Okay, fine, buy the app, whatever”. To see kids just naturally have a knack for figuring things out, before… I think it is maybe they are not programmed yet to shun things that they do not understand. It is intriguing to watch them, it is really cool that you do that.
Anne Gentle: It is fun. They will dig in.
Niki Acosta: Let us switch gears a little bit, because I know that there is a lot happening in docs world, currently, and we do have a question from Yadine, who is watching. First, before we get into that question, tell us about your role as the Doc Lead for OpenStack. What do you do, what are you responsible for, how do you work with folks, that kind of stuff.
Anne Gentle: Yes, sure. This is actually a really exciting time because the Kilo release just went out last Thursday, and I actually did not run for the project team lead for documentation this round. Lana Brindley, a Racker out of Australia is taking over the role. I am not disappearing, or anything like that, but I am going to move into a lot more on the app developer API, STK, documentation work, that consumer of docs. Just to give a broad overview of focused-app documentation, I am glad you asked, documentation matters! We do community-sourced docs, we treat the docs like code. If you take nothing away, just treat the docs like code. We review each others patches, we have a style guide of conventions that everyone should follow, we use Launchpad to track issues, just like a bug, there are doc bugs as well.
Every single page of the doc site lets you log a bug. In that way, we are everybody who contributes to the docs is a technical contributor. We use Garrett, we use the same work flows for reviews and all of the things that you would do with code, we do that with the docs; including continuous integration and automated build. As soon as a patch is reviewed by two docs board members, it is pushed live to the doc site.
Niki Acosta: How many people currently are contributing to docs in OpenStack?
Anne Gentle: It is actually a really good question. I did deep dive study on who … If you look at every doc everywhere, we had almost 200 contributors in the last six months, which is a record again. It just keeps growing. What I actually did a study on was, which documents are they contributing to? Because we have a library of documentation now, it is a really nice robust set of docs. The most contributed to document, in the last six months, was the security guide. They did a real push on updating it, getting more updates to that actual tooling that helps you secure an OpenStack cloud; here is what is exciting to me: the second most contributors where … The definition I used was contributed more than two patches, we had the most for the API reference. API, developer.openstack.org/API/ref is where that is billed to.
It was really exciting to see, we have had 120 contributors all-time to that, but 50 of those were in the last six months, that is partially what we are trying to build up is … We have a lot of operator docs, let us move into the “How do I consume OpenStack clouds doc-land”?
Niki Acosta: You know what, Anne? I am getting reports that you are still breaking up a little, I am definitely seeing it on my side. Can you do my a quick favor and log out, and then rejoin?”
Anne Gentle: Yes.
Niki Acosta: Thanks. The beauty of live broadcast, Ladies and Gentlemen. And thank you, Yadine, for letting me harass you to see if you are seeing that on your side as well. I appreciate you.
Anne Gentle: Okay. Any better?
Niki Acosta: Maybe?
Anne Gentle: Maybe?
Niki Acosta: I am crossing my fingers. You said you are hard-wired in?
Anne Gentle: Yes, I am. And it is sad, because I specifically turned WiFi off. I can try WiFi, should I try it?
Niki Acosta: Yes, because you are still breaking up.
Anne Gentle: Man. What is up. All right, let me try WiFi. Okay. Any better?
Niki Acosta: So far so good.
Anne Gentle: Fingers crossed.
Niki Acosta: Fingers crossed. Goodnight. Thank you inter-webs.
Anne Gentle: Yes.
Niki Acosta: [inaudible 00:14:21] few most exciting packets with regards to the community and the technology.
Anne Gentle: You asked what is making me most excited about the technology coming up?
Niki Acosta: Uh-oh.
Anne Gentle: Now you are jumping, now I am losing you.
Niki Acosta: You might have been better hard-wired in.
Anne Gentle: Yes, let me try it again.
Niki Acosta: You log in early and … Are you in on a different profile …
Anne Gentle: [inaudible 00:15:14] I guess?
Niki Acosta: Weird.
Anne Gentle: How is that, better?
Niki Acosta: Yes. You look great, so far.
Anne Gentle: I am hard-wired, and WiFi is off.
Niki Acosta: Okay. We do troubleshoot this stuff, I do make sure, in the pre-show prep, that everything is working. It was working just fine.
Anne Gentle: It was, I know.
Niki Acosta: We are dropping packets. We had a question, “What makes you most excited about doing docs for OpenStack with regards to the community and the technology?”
Anne Gentle: My favorite story of doing Open source documentation, is going to a training class that we were holding for Rackspace and I went to a dinner and I was like, “I am the OpenStack doc detail, do you have any questions,” and someone came up to me and said, “Thank you for trying to do the impossible.” I was like, that is why I do this, because it is such a challenge, it is so appreciated if you do it well and do it right, that it is just totally worth it. That is what makes me excited. It is innovative, it is … You get to experiment a little, then if things fail, you are like, “Well, we’ll do it differently next time.” It is the fail early, fail fast, try and see, and move on. People are so appreciative.
Niki Acosta: They are like, “Ah! Thank goodness, there’s docs that can actually do stuff now!”
Anne Gentle: Yes!
Niki Acosta: What about the books? I know you have been involved in a few books grants, is that something that you just decided to do just for fun, because it was …
Anne Gentle: No, that is a pretty well-known Open source technique, and people use it for code a lot. You take focused time out, and do a focused effort that is scoped narrowly enough that you can get it done. I had participated in a book sprint for … Do you remember the little XO computer, for kids? I had participated in a book sprint for that in 2008, and then Google hosted four sprints at once and had freelance writers go and help with those. I had participated in three, probably, book sprints before we tried our own with operations guide; hired a facilitator to come in and honestly, I think that is the real success factor was having an outside person who could take that moderator role …
People get really excited about their opinions, but you still have to get it down on paper as an opinion, as a stated resource. We did that with operations guide, we funded and ran one for the security guide. They were in a bunker, in Maryland. That one was a big success. We are tempering the sprint idea with the cost for travel, and what books we actually need next. What is happening with all of the projects coming in, is, honestly the docs cannot take on much more maintenance. That is one of the pitfalls of a sprint, that it adds a new body of work, but the sprinters … The original authors may or may not have the time or inclination to come back to it and maintain it, over time. That has been the struggle, we have this gloriously edited operations guide, but we are not seeing a lot of maintenance on it by the original authors. They are off doing other things, or running their own clouds. It is an interesting space, and gosh, that is 7-8 years I have been looking at that as a technique, now.
Niki Acosta: How do you get people to participate, you put a call out, all these people fly in, and then what? You sit in a room for how long?
Anne Gentle: We literally sat in a room for five days, and you write for three and a half, and edit for a day and a half. Day 1 is Post-it notes, Post-it notes, topics, shape of the book, you really try to start on Day 1 with a pretty good idea. It was a discussion point: do you come in with an outline already decided on? Do you actually make sure that the people who are in the room can write what you need written? It is hard, man. You have to invite, carefully, I want to say. There are people … There was someone at one of the sprints I went to who was a support coordinator, and he could not take the time away from his support cue to write, and the facilitator had to pull him aside and say, “You’re not … You’re not writing like we need you to,”. That is what else can happen, that is why it is so critical to bring the right people in the room, who really can laser focus. Sitting your butt in a seat and writing 4000 – 6000 words in a day, is no small feat. It is disciplined.
Niki Acosta: You dropped again, I am sorry, Anne. When you guys get together and you do this, is it like you are writing an Etherpad to come back, editing, all that stuff?
Anne Gentle: Yes. The tool has evolved over the years. We used a tool, it is hosted, OpenSource software, it is called ‘bookie’, it is like wiki for books. It is also sort of opinionated in itself, because instead of, you know how wikia you can merge anything as long as you do the re-base and bring everything together? With this bookie tool, it locks somebody else out of whatever was being written, so you would never have merges, you never have conflicts. When you are all sitting in a room, you can say across the room, “I’m working on the messaging chapter, when I’m done, I will hand it over to you,”. It is better for the end-person, the tool is specifically for that end-person across the table interaction.
Niki Acosta: Looking at those books … Operations’ guide and security guide, for that matter, at least the previous ones, the first ones have been out for a long time. Do you look back at those and just marvel at how much things have changed at this point?
Anne Gentle: It is interesting, I read through the operations guide and we did very light touches for Kilo. We said, “Oh yeah, CERN, they’ve got a lot more cores now.” It was just a real light touch, because we are only sticking to infrastructure in there. Now, I know it could use a big scrub, but honestly from an operations standpoint … Especially since we … Now, the big update we have had to do, for the O’Reilly edit, was to add Neutron Networking. We could do a scrub for features, at a sense, but honestly with two reference architectures in that book, it is still pretty solid. Now you are paused.
Niki Acosta: Anne, I just completely lost all of that.
Anne Gentle: Oh no, it is like when you freeze, then I can probably say that I am not getting through.
Niki Acosta: Are you using Chrome, by chance?
Anne Gentle: Yes.
Niki Acosta: You are using Chrome.
Anne Gentle: Yes.
Niki Acosta: Do you want to try rejoining with Firefox?
Anne Gentle: I could, okay.
Niki Acosta: Okay.
Anne Gentle: See you in a minute.
Niki Acosta: I am really bummed that this keeps dropping, because Anne is so awesome. We may have to reschedule this one, if this keeps happening. That is my commitment to you, viewers/listeners. Well, viewers, watched … Guys I am really sorry, and gals.
Anne Gentle: I could not get it to work on Firefox.
Niki Acosta: Uh-oh.
Anne Gentle: Yes, it was was, “Plug-in was not going to be allowed,”.
Niki Acosta: I am so bummed, if we keep having problems, I think we should reschedule, Anne, because you are way too important for us to be dropping.
Anne Gentle: Aww.
Niki Acosta: You have so much good stuff to say, and I want to …
Anne Gentle: I wonder if I turn the camera off, if that would let the bandwidth get through. What do you think, is that any better?
Niki Acosta: You sound great, to me. Yes, for sure. Okay, we can run it like that, that works.
Anne Gentle: We can also reschedule so you and I sit together, I mean, geeze.
Niki Acosta: We will be at the Summit, doing podcast from the Summit in … You are probably incredibly, incredibly busy at the Summit because who is not. We are going to do mini podcasts about 20 – 25 minutes long, on Monday and Thursday.
Anne Gentle: Is there certain production where they will glue this back together?
Niki Acosta: Yes, no we are not that sophisticated. It is all automated, we just … Jeff has to call me, and then I just log in as him, then it automatically exports to everything. I do have to review the transcripts for past podcasts which is always, always a treat. I think they are sent, I do not even know where. Potentially to places where English is not the primary language, and so you get, especially technical terms, you get stuff back and you are like, “What? What was that?” And have to re-watch that again.
Anne Gentle: You have some doozies in OpenStack.
Niki Acosta: Totally.
Anne Gentle: It is true.
Niki Acosta: One of the things that Yadine wants to know is, “How have the expectations for documentation changed, with the community since you started working on OpenStack?”
Anne Gentle: Oh. Okay that is a good question. How have the expectations for documentation changed? We have had plenty of discussions around maintaining quality, while keeping up with fast-moving code. I have never lowered my expectations, let me lead with that. We have great writers, we have great communicators in the community, we still do not need to write to a standard, and write to conventions. Honestly, what my expectations, I have always done, are the segmentation of audience. You need to write to an operator when you want to convey something. You need to write to an end-user if you are working on an end-user guide. I think that audience analysis has helped immensely with the quality of the doc, I think it is great for contributor developers to write for each other; they know the audience and they can talk to each other. Now I, last year … Are you still there?
Niki Acosta: Yes. I am still here, I actually turned my camera off, too.
Anne Gentle: Awesome, that will work. I think that has not changed over the years. It has … We have never added … There are audiences we have not addressed yet. What about a DevOps audience? We have not really written a guide for them. What about an SDK developer? We have not written a specific guide for them. I think that with the expansion of OpenStack projects, we should also expand the docs, but boy, that is hard with scarce resources, right? As the leader, you have to make the decisions about what gets written next, and be pretty overly pragmatic. Honestly, you have to look at data, you have to look at stats; who … Where can you find actual contributors, and time for them to carve off, to write what you need written? That kind of thing.
Niki Acosta: You have been pretty successful in recruiting interns and through the GNOME Outreach Program, and other things, haven’t you?
Anne Gentle: Yes. When I was going to the OpenStack Summits and still not seeing a ton of women there, I started looking into the other open source communities about what they are doing to get more women in their communities. The Python community is an excellent job of this, as it turned out, there was a GNOME Outreach Program for women where they noticed that a lot of women were not applying to Google Summer of Code; they set up a mirror internship program, more geared towards women. A couple of things that you do differently, to hire interns who are women, is you do not make them be a student. Women are often entering the workplace or trying out new things and not a student anymore.
Making sure there are opportunities for women who are trying technology or open source as a second career is one of them, the women actually meet their mentors early on and actually work with their mentor on shaping the project. Connecting women early. Honestly, mentors … Research shows that the mentor does not have to be a woman also, it can be anyone in a technology topic you are interested in; find a mentor there. Shaping that project early and meeting the mentor early was another component. A third component, this is where the Summit comes in, is making sure they get to meet in person and get to go to community events, is another component. That has been huge. GNOME has actually moved that program into a new name, called, ‘Outreachy’, which is super fun. We actually named it on Twitter. I found out later Marina, the woman who runs the program as an administrator, let me know that. It is internships, that is another thing – they can do documentation, they can do usability, they can do front-end design, it does not have to be just coding, coding, coding, for their internship.
Niki Acosta: I know that Rackspace, and probably a bunch of other companies too, would actually fund scholarships to get these women to the Summit to actually meet people and do all of the Women in Tech events; it is really cool, last couple of Summits meeting some of those interns and just, for a lot of them, this might be their first conference, ever.
Anne Gentle: Yes. They are so fantastic, I just love seeing the teams interact with the women that they have met, mostly on IRC or chatted with mostly online, and then, “We went and rode on the Ferris Wheel, in Atlanta!” It was just a blast to get to know them better, you feel like you know people when you work with them online, and then you meet them in person and it is like, “Oh, of course I know you!”
Niki Acosta: They are like, “Oh, you’re not as tall as you looked on WebEx or …”.
Anne Gentle: That is me!
Niki Acosta: That is so great. One thing that we were talking about earlier, and we got cut off … I am going to bring this up again because I think it is very important: you are transitioning away from docs as the PTL for docs and Lana Brindley is taking over, which is super cool. What is your ask of people that are writing code for OpenStack in terms of documentation? What would make, and/or in the future Lana’s life, a whole lot easier?
Anne Gentle: We have to write to a standard and really the docs team is going to function in a role of providing the best tools and framework for getting done what needs to be done. I tell you, Lana also is a great leader of enterprise doc teams and has grown a doc team at Rackspace of one, HER, to 8 doc writers. She is also very well-versed and I think her style will be a little different from mine. I never really tried to build a team and make a team work on upstream, here at Rackspace. I think the fact that her team works on upstream half the time is also another shift.
What I want to say is, it is going to have to be specialty teams; we have set that up in the last release, where we have a team working on the install guide only, a team working on the security guide, only; a team working on the user guides only. That is a piece of it, and I think Lana will continue with that. The other piece is going to be automating as much as we can while still maintaining high quality-friendly docs. What I mean by that is, OpenStack is the most configurable thing ever, it really is that knee-deep pile of legos that you wade into. What we have done over the years is automate scraping the code for configuration descriptions, defaults, and a little bit of guidance for configuration, in a very, very granular level.
We have documented, honestly, over 6,000 configuration options in OpenStack; what I think will happen next is we need to apply that kind of mentality to the API reference and the developers will be writing the descriptions, the writers will be editing them, we will make sure that it meets the standard, is friendly and makes sense, but leverage the automation part. Continuous integration for documentation is game-changing. I do not know if there are any documentation geeks hanging out on this podcast, but it is the most amazing thing to engineer docs so that they publish live when you get approval. It really is amazing. And to have a translation tool chain that integrates right in is unbelievable.
It is that really exciting innovation piece, to get a documentation translation tool chain in a 6-month time period was amazing. Another big thrust we have been doing in the last six months is converting from Docbook to RST. Docbook is a very well-established XML standard for writing documentation, but mostly writing books. We used it quite a bit in a topical fashion, but it really was for writing linear things, printable things. By moving to RST, which is Restructured Text, the markup is a lot simpler, the Build-tooling is Sphinx which is a Python-based tool, and I feel like we can get a lot more of our Python contributor base working on the docs that way. It is a markup they understand, they see it everyday, and that is the goal. We converted hundreds of files this past release, for the end-user guide and the admin user guide to be offered in RST now. Super simple, super clean, the [sci-fi/sci-diffs 00:36:07] are real easy to compare and read, so reviews should go quicker, too. It is a really exciting conversion time. I do not know if that answered the question, sorry.
Niki Acosta: Yes, totally. It is part your ask from folks who are submitting new features, or patches, or whatever; are you making the ask that they take the time to really put some love into it?
Anne Gentle: Yes! Really empathize with the person who is your reader. We do use a flag and commit messages, it is called DocImpact, and that automatically logs a doc bug that someone can come back to and assign themselves to. A lot of times, if a developer uses DocImpact and a patch, I will go ahead and subscribe them to the bug so that they can know to circle back. That is another process-based thing where we really integrate with the code, to do the automation of, “This is a task, circle back to do the docs,” kind of thing. We also have API impact, that is actually really helpful for docs as well, where you have to remember that you are reviewing this to make sure there are no backwards incompatible changes introduced, make sure that the API column makes sense to the person who would be using it. Again, it is that empathy-based shift to try to look at it in the shoes of the person trying to use this feature.
Niki Acosta: I do not, with MetaCloud, now Cisco/OpenStack private Cloud, we actually in our support portal, just point straight to the OpenStack docs, but it is kind of a double-edged sword for us, because we may not be running the latest and greatest code release, in some cases, until we are sure that it is stable and can meet our requirements for scale. Are you saying that other companies are heavily relying straight up on just OpenStack docs themselves? Are people taking components from what you are putting together and turning that into other things for their customers?
Anne Gentle: You know, originally, why I chose Docbooks, because I really thought Red Hat was a Docbook shop and they would be reusing parts of the OpenStack upstream and rebranding it for Red Hat, and in fact, they have done that. They have a lot of automation that does that, they just rebrand it as Red Hat. I do not think that is totally necessary. What we do for a lot of the docs and end-user docs is, even if it is something new for Kilo, we leave in the instructions for Juno so that somebody that comes up to that particular guide will have … We do not know what cloud they are running.
Niki Acosta: Right.
Anne Gentle: Honestly, ideally all of the OpenStack upstream documentation is licensed in such a way that it is completely reusable and with attribution, you are going to have to say that, “Yes we got this from the OpenStack doc site,” but honestly, that is our goal: license it in such a way that people can reuse it however they wish as long as they are respectful of the logo and the brand guidelines. Do not slap an OpenStack logo on it unless you have the legal permission to do that. Just use the words, use the instructions absolutely.
Niki Acosta: I love that, I think that is the reason why OpenStack has gotten so far is because it was found with the intent of being an open source project, which is really cool and probably far easier to go that route than to open stuff up at a later date and saying, “Hey, we’ve been running this thing forever, now with open source,” people will look like, “what?”
Anne Gentle: It still surprised me, I want to say, my first month working at OpenStack somebody asked if all the fonts were open source. I was like, “uh,” and I had to look it up. But man, yes, we are serious about open source docs.
Niki Acosta: That is really cool. One of the things you said you are going to be working on was docs focused on application developers and probably less focused on infrastructure folks. Can you kind of talk about some of the things that you plan to do, as far as app developer documentation goes? I think that is really exciting.
Anne Gentle: Yes. We are preparing for the OpenStack Summit, and two of the … For the design some aside, we tend to have sessions where we have an open discussion about, “Can you please tell me if this design idea, for this work I want to do in the next release, is something that will work in the community,”. One of them is a cross-project section about standardizing the surface catalog. As an app developer, the first thing you have to do when you walk up to any OpenStack cloud is say, “This is me, can I have a token please? Here are my credentials that say I should have that.” Then, in return you get this ginormous, in some cases, service catalog.
I actually did a little bit of an analysis when I would go to try stack, what does this service catalog look like; Rackspace private cloud what does the catalog look like, Rackspace public cloud, what does the catalog look like? I am forgetting some, but like, Mirantis private cloud’s, HP’s public cloud, what does the service catalog look like? Monty Taylor had done a lot of work as well, on looking at 4 – 5 public clouds and seeing what he was getting back. He was like, “Wait, what, wait, wait, we need some standards here,” so that is one of the sessions I am going to be working on is: right now for a service catalog, people just kind of copy whatever DevStack did, which has more of an eye to a contributor developer than an app developer. Those are important distinctions to make, in the application and work load ecosystem where you are just trying to run this giant website and make sure that it does not go down during an event or … You do not care about anything except for maybe object storage at that particular moment. Either way is to kind of make sure the service catalog is user-friendly, can you filter it, can you make it less of a headache to get back, especially from multiple providers. That is one session.
Some of that is a documentation thing, some of that is a standardization thing. I serve on the technical committee for OpenStack and I have six more months to serve there until election cycle comes back again. Some of my work is that broader view of OpenStack as a whole, how can we make … Even as we keep adding projects, how do we make sure that we make the basics usable? Another session is going to be really interesting; I talked earlier about how we have got 6,000 configuration options documented and I am trying to think of how to apply that concept of scraping the code for the reference information, to API reference documentation itself. Can we scrape and build resource parameters and all kinds of API definitions from the code itself so that it is maintainable? It is halfway there, so how can I build a community-sourced developers guide that shows people how to make really cool applications on OpenStack clouds? We had a first-app tutorial sprint earlier this release, six months, and they just went through a whole bunch of Python examples, adding small things at a time to an application so that it walks people through in a very building block way. That is the kind of person I want to be gearing towards in writing a lot more for this next release.
Niki Acosta: Do you think that people do not write applications on OpenStack because those kinds of resources do not exist? Or do you think those resources start to exist when people start writing applications on OpenStack; it is kind of a chicken and egg situation.
Anne Gentle: Chicken and egg. There is a little bit of that, I think that Amazon, AWS has dominated the developer market for years now and they probably have a 10 – 12 year head start on us. We are just behind and trying to catch up, and catching up in community resourced ways sometimes you end up with this lovely surprise. Honestly, we had the entire OpenStack glossary written up over a weekend by a system administrator in Iowa, I kid you not. I think there is going to be lovely surprises like that, and we are going to have to, as a community, figure out how to adopt them into the open transparent techniques that we have for docs.
I will be honest, I think we are behind, and I work on the developer experience team here at Rackspace, I went to a cross clubs workshop where we got an AWS account, an HP cloud account, a Rackspace cloud account and then used cross cloud SDKs to spin up resources to either run like a small flask app was one of them, or run a web service with a load balancer in front of it, was maybe another one? We did something very similar at Grace Hopper, Grace Hopper is the all women technology conference. As opposed to the thousands of men and hundreds of women at a lot of technology conferences, this was 8,000 women in technology and we had a blast. It is just [inaudible 00:46:33] put together this workshop where we went through here’s how you do a humanitarian app on OpenStack clouds, with Rackspace clouds and go to town get your token and give it to web cloud, web cloud will spin up servers and web master and make your app rock solid. I just think that we have to keep writing those workshops, sharing in the community and figure out how to community-source those.
It has been tough. It is really hard to build a writing community out of nowhere. It is a marathon, not a sprint. I still think I am four years in and I still think there are new areas to explore. Four and a half years in now, Geeze Louise. This is my 10th Summit.
Niki Acosta: Oh my Gosh. I think it will be my ninth, or eighth, I’m not sure. It is crazy to see how much they have grown. That is really cool, that you guys are doing these labs. It is …
Anne Gentle: Can I share?
Niki Acosta: Yes sure.
Anne Gentle: I have another story: I am trying to learn how to set up infrastructure so this is a personal story. Last summer, my older son was diagnosed with Type I Diabetes, and I do not know how many people listening know a lot about it, but it is an insulin-dependent and highly … You are very required to manage a lot of numbers and data for him. Since he is 11, he is sort of at that cusp of, he is going to need a lot of helpers along the way. You cannot expect an 11 year old kid just to be like, “Oh yeah, I’ve gotta do injections and I’ve gotta check my blood sugar and,” it is just really hard. The amazing thing is there is technology now where he can wear a sensor on his body, and it sends information over Bluetooth to this receiver and now, just I guess just three weeks ago, the company that does the sender and receiver has the technology for using Bluetooth to send to an iPhone, and the iPhone is actually sending out the data through a RESTful API.
Niki, I have all this stuff and there is an open source project called “Night Scout” that could actually take that data from it’s called Dexcom, take the data from the sensor, I actually stood up on the Rackspace cloud on OpenStack servers a node.JS server from this open source project that basically listens in on data and my husband and I now can use Night Scout to monitor his glucose everyday, is it high, is it low, if it is high is it because he just ate, how much is the insulin he just took affecting him? It is really amazing that in doing so, I learned, “Oh, here’s how I make sure it’s on a super secret court number, and all of this sort of locking down of this application server,” it is really just my husband and I, and the babysitter, occasionally.
Niki Acosta: Are you contributing to Night Scout at this point?
Anne Gentle: I need to, but I have not really found an in, yet, because I do not know enough about node.JS to fix anything even if it needs fixing. I really would like to contribute to the documentation,
Niki Acosta: I was going to say, “How ’bout docs?”
Anne Gentle: Oh really. Absolutely. Really, I could do this for free because I have Rackspace cloud account and as Rackspace employees we get lots of cloud, it is pretty awesome. Trying to think of other parents who are not cloud savvy or they actually do a lot with a [Zoro 00:50:25] websites is one of the ways to do this and AWS and Heroku are also a couple of the known methods for deploying this stuff. Even just looking for ways I can contribute to deployment ideas would be fantastic.
Niki Acosta: I know you do this because you love your son, kudos to you because it is kind of mind-blowing, that technology like that exists, but I could foresee somebody setting this up on a deployment subscription basis where they kind of handle all the infrastructure for you, and ta-da you create an account and go.
Anne Gentle: Yes. It is really amazing, this group, open source group, I actually started crying when I first read this is a dad of a kid who is 11, who said, “Okay, the technology isn’t there yet, what can I do?” He started this open source project, but what brought me to tears is he realized, if I make a mistake other people could have bad treatment plans because of me. If they sue me, I could lose my house. He had to come up with a structure that would let him work in an open source environment while not endangering other people’s lives, or endangering himself for sharing, where he could have been wrong.
I think that is really interesting. What is happening is the open source community is then pushing the proprietary providers to provide features that we all want, and so that is actually working out really well. I am pretty interested in this, is it a healthy community, absolutely. Are they poking each other where they need to poke each other? Yes, they are. What they have done is the FDA approved the proprietary one at 120 days instead of 180 days; I think even government agencies are recognizing, “Oh, wow, they do have this figured out,” especially when you spread the data across hundreds of thousands of people, that is where the proof comes in too, that it is safe that you are not going to risk your life using some open source technology.
Niki Acosta: I can definitely see the inherent risk that someone might take on, from doing that. I just found, nightscoutfoundation.org. It looks like they do take donations as well, so in honor of you and your son, Jeff and I are going to make a donation on your son’s behalf to the Night Scout Foundation, because it is a really cool org … It is amazing what people will do if they just have the information, or have the API, or have access to be able to write their own applications using these things.
Anne Gentle: Yes.
Niki Acosta: It is really cool, I can definitely see, I was talking earlier about my son playing that Blocksworld game; it definitely seems like an exciting future, you look at technology and where it is today. I love home automation, I am so geeked out. If it does not work with an app, or some of the other, I will say: ‘user-friendly’ tools that are out there, than I am not interested. I am definitely seeing a shift, and I think it is definitely a matter of time before we see that in full force in healthcare, because healthcare you probably realize is a pretty well-guarded industry.
Anne Gentle: Yes, and where computers can have the data themselves and make their decisions.
Niki Acosta: Maybe you are right, a staff platform will violate HIPAA laws or something, so you could …
Anne Gentle: I said, “What’s the risk? Do I have to run my own son’s data? Through HIPAA?”
Niki Acosta: Right, I guess if you own your own health data, I do not know if it is subject to HIPAA privacy laws, that is a good …
Anne Gentle: Right. Especially with a parent/child, yes, is it automatic? I do not even know.
Niki Acosta: That is really cool, it is really amazing that you get to have that opportunity to check out what your son’s health is like from technology. Amazing. I have a question, because I wonder about this. We have interviewed a ton of people in the open set community, and a couple of people and PTL’s and former PTL’s, what is your take on some of these technical meanings, what actually happens behind closed doors, Anne.
Anne Gentle: Behind closed doors? Gosh. We do not have any of those. I cannot recall, what really happens. I guess it is funny, I have had to contact all of the PTLs to do some work, to move around some API docs in the past, sometimes I will email only the PTLs, so that has happened. I mean, over beers, whatever happens, happens over beers.
Niki Acosta: It seems like …
Anne Gentle: I still think the most smart people at the Summit are the ones who stay stone sober and you do not know it, and you might tell them stuff, you think they are drunk and they are not. That is a very interesting person at a Summit. Watch out for those.
Niki Acosta: That would not be me, ever.
Anne Gentle: I mean really, this community does respect the open and maybe because I am sort of naive and, “Oh, docs plan, and everybody’s open.” I do not have to have closed-door conversations about to license a doc in this way. I just have not had to have very many battles like that, I guess.
Niki Acosta: Who are the top companies that are allocating resources specifically to documentation?
Anne Gentle: It has to be Rackspace and Mirantis, building up teams, getting them in review states where they are added to docs core. We added a lot of people to docs core in the last release because we were noticing, “Hey, you are doing a lot of good reviews, you are making sure that the stuff coming in and the stuff getting published is what we want it to be.” Mirantis and Rackspace; it is a lot of [inaudible 00:56:44] and Rackspace is really the one who built that team from nothing to 8 people. Nick Chase over in Mirantis is building up teams, we are trying to figure out if we can hire a contractors and sometimes that works and sometimes it does not. Can we hire people to write on spec for very specific things we need written?
So far, we have not had a lot of success with that. I really appreciate Rackspace reporting me over the years, to go and do this crazy collaborative open source doc thing, “Okay Anne, you go figure it out!” It has been awesome, it has been really great. I have got leadership now as a developer experience team, and Jessie Knowler … I am being shown things that are just super exciting about how to be strategic about our contributions, strategic about what tooling we use, even to get the job done. Especially, over four and a half years, we are going to have to reinvent the tooling, go into RST, this last release is super, super challenging, but we did it as a group.
Niki Acosta: What is your … Obviously you guys are always, always, always … I should not say, “You guys,” … Y’all. Y’all seems to be a more gender-inclusive term. Y’all are always looking for people to help write docs so if someone is thinking, if any of our viewers out there are thinking about how they fit into the ecosystem, what it your pitch to them, to come and write docs?
Anne Gentle: I actually really would like current contributors to write docs, honestly it is really hard to get Garrett set up, so we do not have a lot of walk up contributors, I call them. It is just like, “Um, I’m just gonna do this quick typo fix,”. No, I would love to get you into something meaty that really interests you, so install OpenStack, see if you can get it running either through DevStack or, if you have access to servers, install it there. See what intrigues you; maybe you are really interested in the identity admin portion, we have not had a lot of stuff written specific to someone just running a federated identity in OpenStack. Goodnight, we would love that! A lot of it is, what is your background already, what do you know already because I really want …
That is the hardest part, right, is do you already have access to an OpenStack cloud? What can you write that nobody else knows yet? How can you share your experiences with others like you? I will say it again: get the devs written for devs, the ops written ops, get an admin written for another admin. That is where the docs are really going to take off. That is where people can get going.
Niki Acosta: I would love to see, even, docs on people who are basically creating products from OpenStack.
Anne Gentle: Oh, interesting, yes.
Niki Acosta: A product, a “How-To” guide for someone who wants to build a product of service on top of OpenStack. I guess, part of it is operators, part of it is, I think, what you are going to be working on with some of the more app developer focused stuff.
Anne Gentle: Yes. How do you get a workload shift?
Niki Acosta: How do you actually architect an application to ensure anti-affinity and somehow orchestrate automatic scaling? Somebody is going to get into that realm and the documentation is there and it becomes easier for people to do it … One thing, I think Amazon is really good at, is they make it really easy to just do what you love and not focus on the “boring stuff,” nobody wants to configure a load balancer, that is just boring.
Anne Gentle: Right, Yes.
Niki Acosta: I foresee something like, the Murano project, and some of the application oriented projects come along and where people start writing Heat templates for stuff. By the way, I did not realize, actually I did realize it awhile ago; I forgot that OpenStack at Rackspace, the team there actually open sourced all their Heat templates for all of the stuff that is in their Rackspace portal, which is great! That [crosstalk 01:02:00]
Anne Gentle: It is like highly available stuff, it is like all the stuff that I need to learn about deployment, they have already done it for years, and they are really good at it. You read their Heat templates as best practices for really hardening your stuff.
Niki Acosta: Totally. Our Cisco team was like, “Hey, y’know, we’re thinking about, y’know, kinda putting together some, some templates that people can use,” so I sent the URL to the developers, and they were like, “Oh, it’s already been done.” How do we borrow from that?
Anne Gentle: Yes. What I am hoping is, we added a link to all the Heat template repositories we could find, to … I want to say we added it to, I cannot remember where we added it. It might have been the image guide, but that kind of idea, that … The images guide is one of the most read guides on the whole site, for whatever reason, but I think it is because it is that compilation of that tooling from people who know how to build images really well; you can kind of pick and choose. Yes, that guy has got this figured out, I will take from here, there, a smorgasbord.
Niki Acosta: A smorgasbord. Yes, I am looking at the doc site now, at docs.openstack.org and it is crazy to see how far it has come.
Anne Gentle: Oh yes.
Niki Acosta: With the number of projects that are being added to OpenStack, even core projects and ancillary projects, I can imagine is just … If you take all the docs together I mean, do you have any kind of idea of how many lines of code are in the docs?
Anne Gentle: Oh, goodness. You know, I do not. What I think is exciting is there are many, many days where [docstud openstext 01:02:28] surpasses [dubdub.openstack 01:02:30] in page views, so we know we are doing something right, right?
Niki Acosta: That is really cool. Yes, do you have any sight on the number of downloads for some of the user-guides or the operations guides?
Anne Gentle: Yes, we easily clear about 400,000 visits … Well unique page views per month, yes probably somewhere in the 400,000 range.
Niki Acosta: That is crazy.
Anne Gentle: Yes. It is cool.
Niki Acosta: That is so cool. Anne, I am really bummed that the first half, and thank you for being smart enough to recognize and realize that turning off the cameras would help, I am really bummed that the first half of our interview was a little butchered. I would love if you have the availability to see you on the mini podcasts, for some of that stuff, especially if it is after some of the sessions that you are writing …
Anne Gentle: That would be fun, yes.
Niki Acosta: Just to kind of recap what happened there. If somebody wants to get started with docs or if they have a question, what is the best route for them to go?
Anne Gentle: If they have a question about docs, the openstack-docs mailing list is a great place to start. We are super-friendly and welcoming, we are like, “You like docs too? Come on over!” Start there. We are also in IRC if that is appealing to you, 24-hours because Lana is based in Australia, that is half the globe. I am in North America and we have European contributors who are there, on my overnight. We have coverage if you want to have any kind of real-time chat, that is a great way to do it.
Niki Acosta: I know we can find you @AnneGentle on the Twitters. How can we find you on IRC?
Anne Gentle: I am ‘AnneGentle’ everywhere.
Niki Acosta: “AnneGentle everywhere”.
Anne Gentle: Very unique, I know.
Niki Acosta: I know, that is what you get for having an awesome name. Believe it or not, there is another Nicole Acosta at Cisco and I have already been getting email mix-ups, so not only do I have a doppleganger with a twin sister of a someone who looks like me, but I also have someone who has the same name as me.
Anne Gentle: How funny.
Niki Acosta: I know, right? Anne it has been a pleasure. I can honestly say without a shadow of a doubt that there is no woman who has done more for OpenStack than you, and I know that the community recognizes it, the technical team recognizes it, the foundational team recognizes it, your co-workers at Rackspace recognize it, and for whatever it is worth, I recognize it too.
Anne Gentle: Thank you.
Niki Acosta: I do not know how you manage to balance doing stuff for OpenStack, doing stuff for Rackspace, being an amazing mom, an amazing wife, but I definitely look up to you and I thank you enough for being the awesome person that you are.
Anne Gentle: Aw, I appreciate that.
Niki Acosta: Yay!
Anne Gentle: It is fun, it is exciting, we have got to keep things going, right?
Niki Acosta: We are both participating in the Women of OpenStack event, there is a private chartered cruise on Sunday night.
Anne Gentle: Love that.
Niki Acosta: If you guys are curious about that, I will tweet out the RSVP link if you would like to attend. There is also a Women of OpenStack mailing list that you can join, I know there is a docs mailing list that you can join, check out the OpenStack site if you are curious about that. We do not have a show next week, but we will be at the OpenStack Summit, we are live-broadcasting Monday and Thursday. Hopefully we will see everyone there.
Anne Gentle: Oh cool!
Niki Acosta: Well, it will not be live, it will be recorded and then uploaded shortly after. We have slots for 24 mini podcasts, and I think we still have room for a few more, if you are interested definitely hit myself or Jeff up on Twitter. You can reach me @NikiAcosta. Anne, thanks again, I cannot wait to see you and give you a hug. Funny enough, we live in the same town and I do not get to see you enough. We should have done this in person, but hindsight, and all.
Anne Gentle: I know, 20/20.
Niki Acosta: 20/20. Thanks for joining us, follow Anne, check out Rackspace, they do have a developer program where you can get free access to cloud, which is really, really cool especially if you are just getting started. Check out DevStack and until then, did I forget anything, Anne?
Anne Gentle: No.
Niki Acosta: That is it. Thanks for being awesome, Anne, and we will see you in Vancouver.
Anne Gentle: Back at you, Niki.
Niki Acosta: All right, bye everybody! Thanks Yadine for your help!
CONNECT WITH US