 Let's get started everybody. It's busy running around and I think they can find the room now that I tweeted it Everybody will be here right, okay. I am Stefan. I'm a fully I'm at three most that take care of marketing and community mostly and Caleb I'm Caleb willing I work under stuff as the customer advocate intern on the cloud team. Yeah, so today We're gonna talk a little bit about how we've been Serving our customers Dreamost and Developers mostly and how we've gone from taking documentation from upstream and put it into a product knowledge base for the dream of cloud And I don't know how many of you are familiar with Dreamost. It's a company started in 1997 So we survived the first dot-com burst We're still thriving. We're still going on and since then we've been serving Developers people who wanted to be to have a presence online and historically Dreamost has always been the place where not only you get hosting, but you also get a shell for example So it was one of the very few people places on the planet where you could actually do that and we allowed a lot of Interactions we our customers are particularly Attached to to the brand that they get very good customer service and over the years We've gone from going from serving customers that were developers lots with lots of experience or knowledge Hands-on on how to run the systems like PHP system or a patchy system and lamp stack in general we started Offering also product products that were there are mostly hands-off Hosted and managed WordPress as a service. So we started mixing users who want to just customers we just want to write a blog or Be designers and show their their design and Less about development or system administrators So We started losing when we when we deployed open stack and in our product that it's called dream compute We realized that a lot of these new users Existing customers are less familiar with Putting getting their hands dirty on administering the systems So and to give you you know a brief history of doing compute also we launched it for in general General availability in early April. So it's about it's been running for a month great great Welcome or you know great reactions from from users but Finally in the super user award too. We have seen today that we got close to winning close and So we're catering to developers and people who want to create Systems create applications deploy their applications on a full scale Open-stack public cloud and We realized once will I started there about a year ago After the Vancouver summit basically and I started looking at the the way the I surveyed our customers in the beta program dream compute beta program and I realized that we were Talking about a lot about these amazing things that the cloud could do we had Been proposing this thing that you could you know if you could run around the block with it You could build things Fantastic and amazing, but then we were just throwing them pieces We were giving them the building block and say you can do it you can do it too And it was it felt to me like we had this wonderful play playground the full of all the bells and whistles the We were talking about compute and virtual servers and memory and scaling up scanning out and networks that you can create and destroy and level 2 or level 3 and storage you know in all the you know kind of Declination but we were not we were not giving users enough information enough inspiration on how to do things So I started looking at how we can inspire and instruct our customer based That's our the mission of our team at this point. It's to instruct them on With documents to do basic things how to run my SQL in dream compute or in open stack and we're working with strong constraints, I mean the very Visible thing is that it's we are very small as a team It's only at this moment him and I Caleb and I So we have to be smart about how to do things we cannot go after huge We cannot build a huge documentation base from scratch only by ourselves So we want to reuse as much as possible We want automate all the things and we want to collaborate with others doing similar things which is the same approach that open stack took five six years ago starting from Austin when they started talking about code and we wanted to do the same for documentation and So we want to reuse as much as possible information that is available upstream from upstream the documentation that the open stack Community has put together for application developers. It's quite comprehensive Although it's well tested Although it's still in in quantity is limited. There is a very nice First application for open stack, but that's pretty much it and then there are the basic building blocks Like how to use Nova how to Nova client or open stack client Or how to use horizon. So we want to reuse as much as possible That is there we want to automate as you know the documentation from open stack upstream is written into RST format restructure text And we want to publish. I mean the end result is always HTML so we want to go from RST to HTML in a manageable way, but make it automatic And we also want to collaborate because we know that we can write bits and pieces about how to deploy a lamp stack on on Dream compute And someone else will write about the engine X or the MongoDB and how we can mix and match all of those we want to do that together with others and so our ideal scenario is That we pull documentation that is Done in a collaboration out there call it upstream. We build the documentation from the restructure text into HTML. We put that documentation into a help desk system or publishing system and and We keep on working on that Receive patches from other our customers or someone someone else's customer and we keep on pushing up and give that cycle a very good feeling and Useful so we start venturing out there with this idea about nine months ago We started putting it together the systems and you know, I went into the company at three most as I said less than a year ago and They were already selecting the software for a comprehensive help center where the company was running on media Wiki That required Changes updates. We want want to get rid of Media Wiki on one hand Get rid of the forums that are used by our customers right now and also get rid of the The idea was to get rid of the ticketing system that the support people are using and get into an integrated platform So the selection process was done before I arrived and we ended up getting with Zen desk So which is a good choice in many aspects because it's got a very powerful rest API But you know, we started to get into limitations as we were going along So I'll pass this to Caleb who's gonna talk about more how of the technical bits of the integration with Zendesk that we've done so Stuff mentioned that it's all RST when it's written and then it has to make its way into HTML Which is done with the same simple talks command that calls Sphinx And then it has to make its way into Zendesk and there's sort of two ways to do that you can like Manually copy and paste the HTML that's built into a web UI and That's that's doable But once you have more than like five articles it gets really tedious and really boring But thankfully Zendesk provides us with a decent REST API so I wrote a Python tool just to take an HTML file and And just basically just throw it at Zendesk and put it in the right place and whatnot And it figures out how to upload images that are referenced locally So it'll put them up onto Zendesk so that they can actually be shown in in line in the text But it can't fix articles that are linked locally. That's something that I'm looking into and There's the GitHub link to that script This is a basic Example of how that runs. You just run the script give it a HTML file and give it the Section ID because in Zendesk every article is in a section And it just it gives you back the URL for where it's at So that's great for one article But what if you have 50 or a hundred and you do something that requires you to Update all of them and push them back to Zendesk. That's really tedious if you have to Tell the script to run each one and you have to tell it also what section to put it in because if you tell it the wrong section It'll just duplicate the article and it won't update the old one So I I came up with this simple YAML thing and the first field is just the section ID the second one is the directory that the Article lives in relative to this file and then inside of that is a list of HTML files that you want to publish to that section And that just it just loops through all of them pushes them up and gives you links back And so after that our workflow looks somewhat like this we fork from Garrett the upstream Garrett into GitHub and the The article writer just clones it makes changes and pushes back to GitHub pushes on to master pushes on to a branch and once it gets merged on to master they would also build the Articles and use the script to push them to Zendesk This is much better than copying and pasting the HTML into the web UI, but it's still not perfect because that requires The the article writer to have an account and be able to push things back to Zendesk which in itself is an issue So we we wrote a Jenkins job All it really does is just pulls GitHub for a new commit on master and once it finds one It just takes diffs between the current commit on master and the last one that it ran on and finds all the articles that have changed if they've changed it pushes them up to Zendesk and This is sort of what it looks like now We fork from Garrett the all the article writer cares about is making changes and getting them merged onto master And then Jenkins abstracts away the layer that is publishing to Zendesk because that's tedious and also like stuff mentioned We want people who are outside of dream host to be able to commit to commit back into our documentation Which they can't do in the old way because they wouldn't have a Login that would allow them to push back into Zendesk right the business model of Zendesk is to sell your accounts Yeah, so we have only one account and many people can publish to push to GitHub Anybody can publish to get up just don't tell them that So we do that for for several upstream repos including the open-stack manuals repo Which we take the user guide out of and the API site repo, which has the first app Which basically gives you a quick rundown of how to Effectively use the cloud to deploy an application, but we also have our specific Documentation that is an upstream that we think we need for our users and that's just basic instructions on how to do common Ops things so like setting up a lamp stack That's important lots of our users do that kind of thing or how to use ansible to to spin up some instances on dream compute And like we said anybody can contribute you make a pull request one of us will Review it if it gets merged into master then Jenkins to take care of the rest So this all sounds great, right But it it's it's it works it has some issues there's lots of things that we still want to work on to improve some features that we want to add some things that we want to make Jenkins do that it doesn't current currently do and After you fork getting the the new updates from upstream is still a very manual process And I'm going to talk about that a little bit more in a bit So some of the limitations of using the upstream docs is that I'm sure as everybody here knows every open stack cloud is different The upstream stuff sort of documents a general open stack cloud But the open stack you run is probably not that cloud It's going to maybe support a little bit more than is documented upstream and it might The upstream documentation might even document things that you don't support what you don't want to be telling your users that you do support And Zendesk doesn't support related page as well. So in Zendesk, you sort of have this hierarchy Or yeah, you have this hierarchy of a category a section and an article and there's you can't Build deeper than that. You can't have a category and then a section nested in a section and then an article Which makes it harder to group your articles So that's an issue that we've had to work around And then that's also supports tags, but it's still not clear to anyone. We asked how to Expose those tags to users. So there is no way to cross link. So if something is about PHP and you want to get all the articles tagged PHP Can't do that and also some of the things that are That come out of the the built upstream docs don't work well in Zendesk So if you see on the on the left side of the slide, there's a table of contents and when you put that into the body of a Zendesk site it like it does some weird formatting things because the CSS isn't there or something and it like it it basically It looks really ugly. So we've we've worked around that and then we also Change some titles. Yeah, the other thing you go back a little bit The other thing that you want to be we notice is that a lot of the documentation from upstream is written as a book and Although the page about launching an instance from the command line or from horizon is self-contained It's it's part of a larger Collection of documents that are all visible into that table of content So kind of stripping that table of content and leaving Launch instances as a title as a head header It's not really that useful when you just use it as an individual page in in our Zendesk And so we edit the contents of the documentation as you sort of just have to because The upstream docs aren't perfect for what you need. They're good for upstream stuff But in in your if you're running a public cloud You need to be able to tweak that and part of what we do is we add our our specific stuff that we support like Public networking or stuff like that and then we also make changes for SEO reasons So we we change the word open stack to like dream compute, which is our product and that also helps prevent confusion because Some of our users might not understand when they're reading the docs when it says open stack It really means, you know, what they're using and that can be confusing and then we also edit the build configs So like like we showed in the last slide that we don't publish a sidebar Because it messes things up So we change the build config so that that isn't an issue and we use an alabaster theme The alabaster theme instead of using the open stack theme because that allowed us to do that easily in retrospect it would have made more sense to To try avoid doing that if possible for reasons that we're gonna talk about now Maybe not. Okay. Well, this is a basic Diff from the tip of the master of our fork to where we forked it so you can see the we changed the title from access an instance through a console to how to access a dream compute instance through a console and then Open stack supports three different kinds of remote console tools and we only support one no VNC so We just strip out the documentation that says we support the other things and change the wording a little bit so it makes more sense and Then this is what that article looks like after it's made its way into Zendesk So it it gets messy because once Editing the build configs is dangerous because if you decide and this is an issue that we've somewhat hit We're using a different sphinx version than upstream Which is a big no-no because the upstream community could decide to use a part of Sphinx that is supported in that version But isn't supported in your version and at that point you have to figure out a workaround or find a way to get back Onto that version with the documentation that you have which is that's a mess. Don't do that and then pulling the updates from upstream gets gets harder the more you change each article because Just basically how how that works is you do a rebase of your patches onto the current upstream master and If there are merge conflicts you have to resolve them manually and it's very tedious and not fun This is This is yeah, so we have lots of different kinds of users We have we have people who are new to cloud people who are not new to cloud but are new to open stack people who are familiar with open stack and We sort of have to work around Doing that and we have to be able to teach the users that are new to cloud How to properly use the cloud and our cloud specifically? Without boring the people who are veterans with with using cloud and and make sure that they just get the information That they need how they want it and if if you're not sure what you're looking at This is a user that tried to They're they're in a VNC console and they typed an SSH command into a login prompt because they were told to do so from the Reading documentation. That's what it says use SSH on the console, but which console Is left to interpretation? Yeah So here's Here's another thing that we found out that Zendesk doesn't not serve our purpose one of the reasons One of the things that I wanted to do With the with with a product knowledge base is to figure out how users are actually using this knowledge base Which articles are being most searched most valuable voted commented on? Which sections which topics which categories are the most popular? Well? Zendesk only has Zendesk only exposes in the URL of the article the actual article path Which means if any of you is familiar with Google Analytics? Google Analytics likes URLs only so when I get into Google Analytics and try to search for the category drink compute cloud servers out of the 170 something categories that we have a section that we have in our knowledge base. I can't I can't I cannot find that information So I cannot filter out which articles are more popular in for cloud servers product and That's a big huge Limitation But I do I do can I can't search I can't see in Google Analytics Which search terms are more familiar with a more are more used but I cannot again I cannot restrict to a path that where that search originated from because that URL is not Carried over in the topic. So It's pretty very limited and some of the knowledge that I wanted to share. I just don't have it unfortunately And but you know the good thing is that we have we're not really dependent on on Zendesk the what we have The fact that we have based our knowledge base off of Restructure text and we actually build it locally we build it and we push it through an API Whatever the API endpoint is shall we decide to move migrate off of Zendesk? Because the company ended up not choosing Zendesk for the tech support bits We can do it and it's interesting because when I started at the company and I proposed initially the idea of using all the cloud documentation Righted in the Restructure text and use this machinery in Python to to push to an API the tech rider team That is working on the hosting and web products at 3 most they were all like Looking at me strange funny like why one why do you want to do that? There is a nice HTML with wig inside Zendesk Why don't you just copy and paste or you know author directly into a browser and I was No I'm sorry. I just not gonna engage into that conversation. I'm not even you know if you want to do it the way I want to do it fine. Otherwise you're happy happy to you know use the the Zendesk Outer in tool and it's funny because in the past couple of weeks They came back to us and said hey, you know what we need to change all of the URLs of our images We need to switch them. How do we do it automatically? They have like 700 articles exactly so So we will probably I mean one of the things that we want to do is to definitely look at another platform for for For our community of documentation to make that more interactive Enable all of the discussion and conversation features around the individual articles And other things that you have to do So what's what's on my plan for the next few weeks or month is to work on the Jenkins job Basically, it's sort of implemented really weird and it's not consistent across the repos which is a bad idea and it only publishes The article it only republishes the article if it sees that the RST changed Because it takes the diff between the git commits and the git commits don't contain the HTML So that's something that I want to change I want it to be smart enough to look at the HTML and take the diffs between that so that it can see When the HTML is changed and not just when the RST file is changed And then the publishing script it's kind of it's a it's fallen to feature creep. I guess There I didn't really have a good view of what I needed out of it until I was already into it knee-deep and It needs to be refactored And the other thing we want to do is definitely get more contributions from customers and non-customers and other users in general into our into our Depository repository and we're I'm starting a program where for no articles new instructions to do tutorials How to tips and tricks? We're gonna give we're gonna give contributors Credit on our cloud and so play a little bit with that And with that I think we're on time for getting questions, too Curiosity's so if you have a question just step up to the mic so that it can be heard on the video And feel free to ask a question I got water Hi, hi, I'm gonna be that guy. Yeah How much do you give back upstream to upstream docks? You can answer that question. Um, so I was a big part of the the shade first app project because Basically when he was he said like make this first app thing happen shade It the docks for shade didn't they didn't exist and so I was like shade is this cool thing I should write that and Then basic things like like typos and and blinks that are bad are easy to commit back upstream but changes in text And obviously things like SEO changes. We're not gonna try push that upstream because that doesn't make any sense But yeah, so for first step we we did a fair bit there and then For for the open stack manuals. It was mostly like typos and bad links and stuff like that Yeah, so the the other while we were playing with shade. He also added Swift supports to shade which was missing in order to complete the first application for open stack So other things that we I have in mind that I still haven't happened is that a lot of the Documentation that we have the how-to's the tutorials for how to do basic operation stuff on any open stack cloud or as They're generic, but I don't know where they would fit into the open stack community right now so lots of the documentation of our application developers right now is First step on open stack, which is still sitting into the first the API site Because a convenience, but it's it's an isolated piece But it's not dedicated. There is no yet a bucket that says, you know, if you are a developer If you want to deploy applications or develop applications targeting open stack. Here's where you go That place is still not existing so I'm hoping that by the end of this week We will have kind of a plan with you with Flanders With all the people involved into the app ecosystem working group So that we can we can play with that and that's another way to give back is to be part of the app like Ecosystem working group where I try to join. Yeah, I think I think so I mentioned things like setting up a lamp stack That's our our that's currently on our own repo, but that that sort of thing I think makes sense to go upstream. We just don't have a place for it currently and yeah Cool Does anybody uses Zendesk or takes you do Interesting so you use Salesforce knowledge base cool. Can you use the mic? Sounds interesting So I was saying we used to use Zendesk for both support and some articles didn't really work out for us Part of it was I mean Zendesk is great But we also want to do a lot of other things not just support cases And I think Zendesk is really really great for support But once you want to do it like a portal for customers with all the rest of the cool stuff It's just a bit limiting. So we switched to Salesforce The support runs from there and also knowledge base is there We're now in the second phase. So we did first implementation of knowledge base, which was interesting but The big challenge we ran into was the whole kind of update articles, right? because the product changes you have to update and a lot of times and You know having a doc team that's gonna also update the knowledge base does really It's complicated because we also have doc team who is responsible for docs and they're like well, you know We don't have time. We don't have resources. How can we find somebody? So we are switching right now into I'm gonna implementing KCS Which is knowledge centeric support basically the idea there and Anybody can actually Google it and find it and like there's bunch of articles and people talking about it and stuff, but it's more Where you relax or enrolls in publishing articles and it becomes more kind of Community driven versus somebody has to approve every single world word and do like all of the you know Reviews and publishers and you know multi-step process where it typically gets stuck somewhere So that's what we're doing in terms of the knowledge base Do you use upstream documentation too? We use portions of it majority way We really try to not use it directly which is provide the links which is another challenge for us because sometimes links change Yeah, and that's something you know We have to do all the time and go and see if there's any bad links But we'll try not to copy the content because then we have to you know Make sure again do same things because we did try it before but then it just merging Becomes complicated make sense any other question What are some things that the upstream? Documentation community could do to help people like you who are trying to use our docs bring them downstream Are there things we could do in an infrastructure way things we could do just generally in terms of our conventions that might make it easier It's a good question I'm Trying to think of something that doesn't sound selfish like something that makes sense for the whole community and not just for us Exactly, and I I can't I can't really think of So to me one of the things that was surprising was to realize how much the Heading the headers the titles of the pages or the articles themselves. They were so generic like launch instances How where and how is that going to help? Users find that information when they Google As it as for SEO purposes, that's not optimal Yeah Yeah, so Yeah, well anywhere they should be they should be looking good I mean we could we could run this there are companies that do the CEO analysis and they could tell us where the the How to optimize the upstream documents and we may want to talk we might want to have that conversation and The other thing that from the very You know egoistic point of view I would like you know the first results to be the dream of documentation Because I mean that's that's actually I mean yeah, well because you know, we're a public User just the right crack space is public client public cloud Deployer so we use the knowledge base We think of use it We hope to use the knowledge base also to drive traffic to to our websites, but So, you know, there is some optimization that I hope that can be done at the at the open-stack level At the same level, I want to see the the community as a whole to help public cloud deploy Deployments to to to get foot to get traffic May I propose very strange idea? How about creating something which looks like the old style web zero one link Ring of links basically open stack documentation generic and there is Drop-down list something which says those those those vendors has own version of this and I believe that That allows user of one service may be big to other Documentation to get the wall picture and it should go to upstream saying this is multi Tenancy documentation something like that. It makes sense. I think it might make sense to to To think about something like that. Yeah web links or Similar approach where where we were talking? I mean one of the things one of the challenges of the the open-stack Application ecosystem working group has been to find places inside. I mean open-stack clouds where The code that was written would run as a test. So let's say I'm a developer I'm sold on this idea of open-stack. I found this great tutorial that teaches me how to deploy a generic Proof of concept as an application on on top of open-stack and Now what where do I go? I got the tutorials? I got the knowledge myself and Where are the API's and the points that I can use and how much are they gonna cost, you know, we're You know, which ones are they and it's funny. It's funny because when when I did it the first time it was Painful it just to run the basic documentation that was written for tri-stack I know for a dev stack installation and a two private clouds When I run it on our public cloud nothing was running I had to tweak and blah blah blah then I found out about shade and then I give it to him I go, okay, you finish. I'm done But other people have tried it in fact there is a talk about this this week from Marcella Bonnell And others at Intel they have done an analysis across Analysis of the developer experience on different clouds public clouds from Amazon to rack space to to to other companies And they're written up the the summary of that. It's it's an interesting topic To continue this idea right now. There is a big topic about Sides continuous integration. I believe the same thing should be applied to all samples in documentation and Maybe some kind of checklist automatic checklist saying this is this is these systems are supporting this not and this gives two Way link you can see all those guys in upstream decided to do something crazy We do not support right now. We should all say them. Please stop or adopt our system And the main thing it should be done by robots not by humans. That's that's true Yeah, it it's basically what ref stock wants to do, but we're real life scenarios instead of abstract API calls That that's a cool idea cool All right. Well, if there are no more questions, I guess we can go get coffee or Hope to the next session. Thank you very much for coming. Thank you