 So first, a little bit about me. I'm from Austin. It's so fun to have this here in our city and get to share it with all of you. Sorry about the weather. My background is software development. I worked as a developer for many years, and then I've also done a lot of developer enablement. So educating developers, getting developers, ramped up on different platforms, and spent a lot of time working on developer experience and API experience. And I think this sign is just the epitome of Austin. Boots, flip flops, and an airstream trailer this way. So you can keep a lookout for that. It's downtown. All right. So many of us at this conference, maybe everyone at this conference, is somehow involved in this picture, going from building monolithic applications to cloud-native microservices. Or maybe you're just starting with the cloud-native microservices. And this is really great. There's so many benefits that you can hear about in oodles of other sessions. So I'm not going to go through them. But these are some of the reasons why you would go down this path. But however you define a microservice, which there's lots of different ways to define it. And this is one, I think, from Microsoft that I just picked. But they all have the idea of services that communicate with each other over standard protocols with defined interfaces. And when I read that last part and you say standard protocols with defined interfaces, this typically means an API. And that starts me down my I worry about developer experience path, which is what I do for Cisco and what I've done for a lot of companies. And so why do we worry about it? And what is developer experience? It's really what is the experience for a developer using an API? And this is really important because developers are users. And what I want to talk about in this section is also your internal developers are even users. If you're building microservices and you're wanting people across organizations or in partner organizations to use some of your APIs, do you have to think about the experience that doesn't just happen by itself? So this is taking some thoughts from worrying about external developer experience and try to put your head around using that to apply to your internal developers. So bad experience means you're making me use it, I don't want to use it, I have a low barrier for leaving and it doesn't spur growth, right? Good experience, I like to use this, I'm going to tell other people about it maybe within my company, within my organization, outside of it, and I'm going to find innovative ways to use it. So this is really the goal that we're striving for. In the API and developer experience like industry thought, there's so much good work that's gone on around how to make your APIs nice for developers to use, right? John Musser, Pamela Fox, there's this wealth of knowledge about what to do, what you need, how you enable these developers. And what I'm finding as I talk to more and more people is there may be people in an organization really focused on that for their external developers, but are you thinking about it for the people within your company who may now be exposing lots and lots of APIs to each other? And this problem, like this is from AppDynamics, which is one of our Cisco products, talking, it's more talking about tracking and visualizing and tracing. But when you think about all the developers, if you have really successful APIs and you have lots of people using them, you end up with this end-to-end world of developers and APIs, and this is what you want, but it adds a lot of complexity to your developer experience. And then what I have found is that when you're building an API for a customer, it's even hard then to get all of the people involved, the writers, the developers, the engineers who come together to create that developer experience. And it's a hard thing to do, right? And when you think about prioritizing that for internal projects, it's even harder because you're running fast, you're moving quickly, and you're not gonna get together all those people and put that same level of emphasis around it like you would for your external audience. How will the teams prioritize the time to create these internal docs? How will they keep them updated when you're really changing quickly? And think about that these good API docs are really the key to bridging organizational boundaries. And there's been a lot of really interesting studies, there's more and more coming out about how these patterns, and when you can bridge those organizational boundaries easier, you really accelerate the innovation that happens inside enterprises, and it's really fueling this rebirth of IT with the composable enterprise. So some of the things that you need just to start thinking, and some of the things that we tackled in this project, you absolutely need API reference docs, that's your first thing, that's the easiest one everyone thinks about. You also need probably some long-form documentation like authentication guides, how do you get started with it? You need some error codes and versioning, you may also want some samples to get people started, right? All the same things you need if you were publishing an API to the external world. And then I think what's really key when you start thinking about microservices and internal teams working in a very rapid DevOps fashion is that all of that really needs to be very tied into your site CICD pipeline. And that's really the piece that I wanna talk about today. So we started looking at how are people doing this, and it's interesting because I work at Cisco and the DevNet organization that I work in, we work with engineering teams all across Cisco, from IoT to data center to networking to cloud to collaboration, all these different technologies. And then we work with a lot of our customers and partners and then we're at conferences and industry places like this. So we've been talking to a lot of people about how are you doing this? What's the story? How are you actually doing this for your internal and external? Are you taking your external practices and implying them internally? Is that too heavy? Is it just happening informally? You know, what are you finding out? And this is a fictional summary of the conversation that I've had. It goes something like this. How are you documenting your internal APIs? Oh, we use Swagger. Awesome, that's great, that's cool. What about additional information like how to authenticate? Oh yeah, we've got some how-tos in a wiki somewhere. Okay, that's pretty good. So Swagger and a wiki and you probably link back and forth. Okay, anything else? No, that's it, that's all. Okay, great. Oh yeah, there are a few teams that also use Raml because they started down that path instead of Swagger and they haven't changed over and maybe they're gonna convert, but right now there's some teams that are using Raml as well. But that is totally it, that's everything. Okay, really? Are you sure? Oh yeah, and there's some stuff in Read the Docs because we did an internal experiment with that with one team. And really, yep, then some teams use Marktown and we've got code samples in GitHub. And then the person having this conversation with us, me, ends up like face palm, like how are you managing all of that? These are all really great tools, right? Like they're all very good for their fit purpose and they fit together. But when you think about that overall experience, it's got some problems. First of all, how do you keep them in sync with what's going on with all your microservices? How do you connect them to your CICD pipeline? That's a bewildering jungle of user experience to find. It leads to a lot of feeling of where's that link? Is it in that Slack channel over here and where did it go? And then where's the magic wiki page that ties all of this together for me? And what do I do? And so then sometimes teams will give up, they won't reach out, they won't have the conversation, they're lost. And then a lot of times, if you're building an internal API, it's really great if you can think about maybe someday that might get opened up externally, right? Maybe it progresses, it grows to be something that you would open up as a service to your customer or your community. And if you don't think about that publishing at the beginning, then you have this really big hurdle when you're ready to open it up externally. So there's no easy path to say, now we're gonna make this API open to the public or to a small few set of people to start doing some trials. It puts a big barrier there. And then there's this issue that I wanna call special attention to you because it's something that comes up in the external work that we do and it also comes up in the internal work. And that's this idea of yes, you need an API reference, definitely. That's pretty much easy. Swagger is open API spec. And a lot of times you can auto-generate it and you can automate that and it's easy to tie in. And people are doing pretty good keeping that up to date. But I always make this analogy that an API reference without some kind of long form documentation is like giving someone a box of bicycle parts that are labeled. This is a handlebar. This is a gear crank. But how do you put it together? Now do you just give them that box and then they're supposed to put it together and ride off down the street? It's not a very good experience. You're sorting through all those pieces, trying to fit how they can fit together. So some kind of long form documentation can really ease that initial friction. Here's the key code sample that you need. Here's how you get authenticated and here's the first thing that you're gonna do. What's your first hello world? But right now you can't really auto-generate that and you can't really automate it very well and there's nothing that really ties together the API reference and the long form documentation in a great format. So we kind of came to this for our Cisco needs and we thought can we build something that can help with this, that can help the teams that we're working with, that can help our own team, that we could maybe look towards bridging that internal to external path, could we address some of these issues? And so we started working on this and we put out some initial ideas around, yes, these are the things, we attributes we want this to have and no, we don't wanna do this when we start down the path of building it. On the yes side, we wanted it to be CICD friendly publishing flow. We wanted it to be developer friendly authoring tools because ideally we're getting the actual engineers writing the microservices to spend a little bit of time documenting it and maybe writing some of that getting started information. So we didn't want it to be something that a tech writer had to get involved with. We wanted it to feel like it fit into your coding tool set and workflow. Ideally we would like to have a central place where you could go and maybe find out about all of your internal APIs. And then because of the breadth of scope that we were working across, we really wanted to maintain some flexibility for each engineering team to make some decisions that fit their problem space very well. So we didn't want it to be overly prescriptive, but we did wanna bring things together. And we wanted to have sample code, docs, all these things in a way that we can keep in sync. What we did not wanna do is we didn't wanna reinvent the wheel. If there was an open source tool that we could use, if there's specifications or things like open API spec, definitely reuse what we can. We didn't wanna build something for proprietary enclose and we didn't wanna strictly enforce only one way of doing things because we knew that simply wouldn't work for the environment of our company. And we didn't want to, we wanted to avoid dropping really key functionality that might be available in some of those best in class tools. So those were kind of some of the things that we set out for. We've accomplished some. We're still on a journey of building it and I think we'll get even further. One of the things that came out of like the stakeholder interviews and things that we did that was really important that stayed through was that we needed to accept multiple inputs and then normalize the output to make it look the same. So I could take Swagger and Ramel but they come out looking like they're tied together. Like it's not jarring when I switch from one to the other that I could take the markdown files and normalize that and give it a consistent output feel. So this was the project. It's a, we call it pub hub. It's just an internal project right now that we're using. And basically that's what it does. It has a front end where you can create projects and you can accept all these different types of documentation, Swagger, markdown, Ramel, some Cisco specific ones that we decided to grapple with and deal with and then other things from the industry. And we actually use some open source tools for being able to process all those different types. And then it's all based through GitHub. So we wanted it to be very much driven as you would code. So this is taking documentation and treating it like code because we were doing it for developers, right? And so it's all managed through Git. You use a very standard commit, tag, push, kind of similar flow that you would. And then you can build it, stage it, publish it. There's notifications through Slack and Spark. And then we have this idea of all those different inputs come in but they all end up looking somewhat tied together. And that was really kind of our goal that we're working toward. So, I think I'm too far away. Go back. I have a really, really short video that just shows like the setup of our project. It doesn't go super deep and it's sped up and you get to see my bad typing. So it's good times. So basically it does have a place where you can initiate the project. You create it. You get your project. You can add contributors here or through GitHub. And then eventually you get your actual repo URL. And then now you're kind of just off to your regular flow. You can work with whatever tools you like to manage your get flow. I'm just doing mine from the command line. I can't type. And then you can see it's very much driven off of, this is a markdown file that I'm typing and it's driven off of a JSON sort of table of contents that glues everything together. And I'm just making a quick change. And then we go back in and you can actually see it in the here. Now it's got my new project and my super cool content. And then from there you could go and do further things. And all of that can hook into your CICD process as needed. Okay. And then this is just some samples of what some of it looks like. So this would be a markdown file that has code snippets inline and you can use different kinds of different languages and have those show up. This can do inline code display or you can do like sort of the stripe three column if you want to have it side by side. So it's some options on that. This is Rammel. I mean, sorry, it's a swagger. So you can see you get most of your normal swagger field and all the normal swagger documentation features. This is Rammel. And now I want to go into the lessons learned because this is the most interesting part. So some of the things that we've been talking to users about and that we've gotten back as feedback. One is that this long form docs plus the API reference really resonated as a problem that everybody was having. And this is across the industry people that I'm talking to, everybody is coming up with different ways to solve this problem, but there's nothing that's really standing out quite yet. And it's really important because as people are getting more specific about their developer experience and they're really encouraging everyone to have those long form docs to make it good. There's this question of how do I keep in sync? How do I tie it together with my API reference from Swagger? The other thing that we've gotten is that from the engineering side, there's been a lot of positive feedback because they're saying this is saving me time. I don't have to think about how I'm gonna format these docs, my internal docs. And I'm very proud to share them around my organization or put them out to people. And I didn't have to spend time coming up with a style sheet or picking a framework or making it match whatever corporate things I want. And they also know that it's a recommended, secure way to do it that we've built and fits all the norms. So it saves them time. They can just start coding. They know how they're gonna document it. And that's been very popular. And that's kind of the second one too is that having a prescribed way to do this and where they don't have to change a lot on their end to fit into it. If they're already using one of these formats, we can accept it and it gives them a path forward. And so that's been a big time saver. And then the multiple input types has just been key. That would be like a non-starter for a lot of groups because you're asking them to go back and rework documentation that they may already have. And then it doesn't end up saving it. This has been a really interesting thing. So the two audiences that this hits is developers and then writers. And when we started it, we were really just thinking about the developers because that was kind of our initial audience. We were working directly with the engineering teams. We knew writers would be involved for external docs but we didn't know if they would be involved for some of the internal documentation. But we've actually found that the writers do you get involved in certain places of it? And certainly for the external documentation, you have these two audiences. And they're different but they are also the same in some ways. The main difference has been around get. So the developers are very happy. They have their normal tool set. Some doc writers, many of them are really making this journey to learn how to work and get and mark down and manage docs that way. But there's a lot of them who that may be really, really new too. And so we've had to spend quite a bit of time with the ones who want to learn it. We actually do office hours. We're doing specific training for them to kind of get them moved over the hump. And that's good, the developers like that because then they feel like the documentation writing is coming more in line with the way they want to manage their docs. And it's easier for them to contribute. And so it's kind of a virtuous cycle. One of the things that we found is that having it in markdown, I was on a call just yesterday with someone. And there was a tech writer and a developer and they were talking. And the developer was like, well I would love to write this part of it but I'm sure this is something really complicated. And they said, oh no, it's just mark down and get. And he was like, oh great, I'll write it then. Which is great when you can get the actual engineers to feel like they are empowered and make time to document it. And so that is something that we are seeing more and more of and it really makes the quality of the information better. And it makes both sides really happy because it just speeds everything up. The other thing is that we've seen with the writers and certain teams, some teams may really want continuous deployment where they're making changes and it's getting deployed actually live. There are other teams who want more sort of, they want to have an approval workflow. They want to say we've delivered it to this point but we want to be able to approve it before it goes out and the rest of the company sees it or whatever. So those are two different cases and we found we really need to solve for both. And then the other one is that the developers really want to push the APIs and automation side of the tooling a lot more. And the writers are not asking for that as much but when they see it happen, they're excited. So that's part of that kind of education as well. Okay, and then some thoughts that we are taking away kind of into the next step of it because we're continuing to evolve this and continuing to grow it. So one is we found you need good docs for your doc tool. It's kind of obvious but it's definitely something to think about and seems a little bit, it may not be as obvious as it should be. And then we found that you should really, like having get and having the workflow around get is really great and gives you tons of benefit and that you should use get for its strengths. Don't be careful not to build something and duplicate something that you can just get through the native functionality. So that's something that we're spending some time thinking about. Once you have a tool that makes it easy for people to contribute to docs across organizational boundaries, just having the tool is not quite enough. There's also some process that needs to happen around how those cross organizational contributions happen. And the way we're treating that is like you would in an actual open source project if you had open source community writing docs, we're just trying to do that internally and pull people in from different organizations, even like sales engineers and people like that who may have really good feedback they wanna add but also putting some process around that so they know what to do, they're comfortable, they know they're doing what they should be doing. The internal, the external path taking the docs and making it so that you're, when you are starting to build your microservice, whether you know if it might ever be externally exposed or not, if you start off in the right way with a good API reference and good docs, having that path to external is easier but it's still bumpy. So there's still a lot of work to do there I think and I think that's a place where there's still improvement to be had. The other thing we found is that this internal developer experience, the more companies, the more customers we talk to, the more people we visit with at shows like this, it's just growing in importance. It's something that I think has been treated within development groups and people have, we've done a great job on our build and test and dev sort of tool set side of things but this part of it of now what you're building has APIs you're exposing to other developers is like the next step we have to get to and if we really want to get to the promise of this composable enterprise with teams really working together and leveraging all this, we're gonna have to figure this out. So it's becoming very important. One of the other things is this kind of project, how do you measure the impact of this kind of project? You could use developer community metrics that you might use for an external developer. You could use those kind of internally to say is this API getting adopted by other groups? What's the usage that's happening? After we did better documentation internally, did we get better usage of it? Are we getting less support requests, that kind of thing. But it's something that we're thinking about, like how do you really measure the impact of something like this? And then we've been talking since the beginning, would this be a project that we would open source? It's very possible. There's a lot of work to be done and there's a lot of figuring out what you can open source in a big company like Cisco, but it's definitely something that is a possibility and we'd love to hear if something like this seems useful to you, if you'd be interested in it as an open source project, things like that. Okay, so if you're interested in all this, there's a couple of things that I will recommend. One of our DevNet team members, her name is Ann Gentel, she wrote a new book called Docs Like Code and it spends a lot of time kind of just around this idea of treating Docs Like Code. Why would you start doing that? How would you start doing it? What are some of the hurdles from the technical writer perspective to starting to treat Docs Like Code? And then she has a site called justrightclick.com where she blogs about these kinds of topics. You can actually read a blog there about this pubhub project that she did recently that has a lot of the same information you heard today and some more detail. So definitely recommend checking that out. And then developer.sysko.com, you can join our community, you can find me there. We've got all kinds of things that developers can play with. So we have sandboxes where you can have your own Kubernetes cluster and all kinds of Cisco platforms that you can code against and it's free for developers. You just reserve your space and start at it. And we have learning labs and tutorials and sample code and all kinds of docs to help you get started. So check it out. And you can find me on Twitter at Mandy Whaley and Cisco DevNet is my organization and we'd love to hear from you. And we have a booth down on the floor with a bunch of Cisco experts in it talking about container networking cloud and multi-cloud type topics. So come find us and I hope you have a great conference. Thanks. Do we do questions or no? Yeah? Okay. Let me get, hold on. I don't know if that's on. What was it? How do you share the common pages? Yeah, that's a good question. So we, right now I'd say it's happening in terms of how you structure the sets of docs. If it's something we know is common, we'll put it into a repo that's got common information and then we can add everyone into that. That's one of our bigger challenges, I think, honestly, is how do we want to handle that? Honestly, we don't have a ton of those right now. In ours, we have some, but it's definitely something to think about. I don't think this is on. No? I'll just try to repeat the question, maybe. Okay, hold on. Okay, just so you look cool. Okay. So my question, I'm not sure it's the same as with the source code and the documentation or is that a documentation only repo that the developer? That's a documentation only repo and then you can add into that anything, any of those formats that you want. And so that you would have pages in there that would be from your Swagger or your Rammel or your Markdown and then we have people who use different automation to take things, if they're generating it from their code, take it from there, send it to that repo and then it pushes it into the docs, so. That's right. Exactly, yeah. We have, we were actually just, so Fabio is one of the architects and developers on this project and we were actually just meeting about some of that yesterday and talking about how you could track sort of aging content, the linting, like some of those different quality metrics that could be brought in. So I think it's definitely needed and it's been on our horizon, but we haven't gotten there quite yet. We'd love to hear more of your ideas. Yeah. So the tool itself, the PubHub tool has a really nice local previewer and web previewer that you can use, so that's very good for the, I'm working and I just wanna see it, I wanna see what I've written and make sure it's looking right and all of that. And then there is a, when you get to a certain point, the person can request or they can do it automated as well to say send to staging, and we have a staging environment and send to prod. So, yeah. But it's, when the individual teams are working on the docs, they can see a very, very like true and exact rendering of it in that previewer. And there's even, there's also like a mobile previewer and they can see the responsive pieces of it and all that. You would have to implement, like some groups would implement that automation and some would not, that's one of the flexibility. Yeah. Cool. Anyone else? Yeah. Yeah, so I can give you my view on it. I think there's a lot of different views, but I think one way to think about it is if it's information that the team is using to build the service, right? Like they're your design documents, your architecture documents, the things that your engineers are using to build and you're getting information there, that's great for like your team, Wiki and sort of internal working documentation. If you're getting to the point where you're saying, this is an API that someone outside of our actual group can use, I think that's where you need to have like swagger and a real reference and some more documentation that has that different hat on instead of being like someone who's in the actual working group. Does that make sense? And that's kind of where you can draw the line. You can do all that documentation in a Wiki, but a lot of Wikis don't handle some of the file types as well and I think it's actually, I think there's actually value in saying these are the documents for our external to the development team, another development team who's going to consume our service like having a process to get there. Yes, depending on the like scale of the organization and who's using internally, you may not want like all of your internal chatter that's in the comments may not be useful to someone in another group, but it might be, so that's a choice that you can make. Yeah. Do you have a specific thought on it? Are you just? Yeah. Yeah, I mean, yeah. I think it's, you get to a point of an API, it's back to like an API as a contract and even for your internal devs, an API as a contract and at what point do you put that stake in the ground and say this is this until we change it and that may change during the maturity of your project. You may get to different points. Right. So you could, you can generate that and then send it into this pub hub flow. So that would be one of the inputs, could be things that come out of that. Yep. Okay, I think we have, yeah, time for one more. We do, we do do localization. We do it in, right now, do we do it in pub? We do, right? We do it in the site. In the site, yeah. So we have a layer on top that's more for external that is more site driven and it's does localization but it's the same built on the same infrastructure as pub hub. So we can, if you want to deep dive with Fabio after we can but yeah, it's, it's basically, we have translators that do the translation and but it's glued together. It knows it's the same document into languages. Anyone else? Good. Okay, thank you guys so much. Really appreciate it. Have a great conference.