AsyncAPI AsyncAPI Conf 2022, 4 Nov 2022

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: How AsyncAPI Docs Got a Facelift: GSoD 2022 Contributions - Alejandra Quetzalli, AsyncAPI Initiative

Description

AsyncAPI Conference 2022 - Day 2
4th November 2022

AsyncAPI is an open-source project that seeks to promote and facilitate the development of asynchronous APIs and event-driven architecture (EDA). In this talk, Alejandra details how contributions from our 2022 GSoD project completely changed the Information Architecture and UX of AsyncAPI Docs. By the end of this talk, the audience will learn about individual writing contributions made by AsyncAPI Docs interns, individual UX improvements incorporated in collaboration with design contributors, and the resulting community feedback.

A

Hola kumustan hello: how are you all and I'm sorry, but I only speak the languages, so I'm gonna have to keep it at that all right. So uh thank you so much for coming this year again to async API conference, uh 2022 so exciting to see a lot of familiar faces here. Also, you know um we are excited about helping build community here, we're excited about open source, but we're also excited about Eda event, driven architecture.

A

So, today, with me, we're going to talk about how our docs have changed a lot over the past year. We're going to talk about specifically a lot of the contributions that came from I just saw uh contract internship um writers. They did a lot of hard work, uh both onboarding and well more about this in the next few slides.

A

So, yes, today's presentation is called how we Syncopy docs got a face, lift as you already know, this is sync story, saw 2022 contributions and for those of you that don't know me yet my name is Alejandra quetzali and I work uh with doing a lot of Open Source work currently with a think. Api initiative and I do Dev docs for sure, but besides being a documentation, engineer, I also find myself accidentally, sometimes doing a little bit of developer relations like today.

A

So here we are- and here you are with me- so welcome- welcome uh if you're kind of new to the initiative, just in case you didn't know uh if you're wondering where to find us in different mediums, different platforms and channels. uh Well, of course, there's our website is thinkify.com and of course today me as I'm speaking about docs I am most enthusiastic about instinctapi.com Docs personally, but we're gonna go see those uh all of those awesome stuff in just a little bit.

A

We also have our GitHub I Sync API same handle our YouTube same handle async API, uh the only one in which we were not so lucky was Twitter because apparently async API was taken, so we had to go with a Sync API spec for those of you that haven't followed us on Twitter. Yet um now you know why we don't just have a Sync API and then in LinkedIn async API got that one and don't forget about slack.

A

If you haven't joined us in slack kid, you should be in our slack, uh mostly because that's essentially our primary form of communication. Aside from, of course, um public, you know, pull request issues, discussions and things like that on GitHub.

A

So, yes, just go to sync api.com and then just super easy, slash, slack, invite and you'll be able to join our Channel and we'll be excited to talk more with you all right. So today we are here to talk about essentially four main things: uh we're gonna share with you, our gsad interview and selection process, how uh we ran it this year on behalf of the initiative, we'll also talk to you about the new things that are happening that have happened since the internship started. Our information architecture has completely changed.

A

If you haven't noticed, and we now have. Finally, the ability to integrate uml diagrams amazing, great engineering diagrams into our documentation, and we really were missing uh more visual elements of learning in our documentation, so I'm very excited about the work on this one and a shout out as well to the person who helped at this dependency and set it all up perfectly on our website because it was uh Magic, but he didn't just you know, update the the uh package he's on file.

A

He actually had to go in and like make a couple of changes to our website, uh so uh big uh shout out to him for his work. So thanks to him, we now have diagrams and then at the end we will also discuss what is left to do for uh 4G sod, which she thought actually will be done not until at the end of November. So, as you can see, there's still a few weeks ahead of work and I'll. Show you what's good.

A

It all is going to look like at the end so that you can better appreciate all the hard work and effort that came from our gsod contributors all right. So if you're wondering hey, you know, I wondered how the interview and the selection process worked uh at least this year, at least in qpi for gsod. What was going on well, I'll, have you know uh we had well over 200 applicants, it was insane. I was like what is happening like every five seconds, like somebody knew was like sending me and responding to you.

A

uh Our request and I just couldn't believe that so many people had seen yes, this tweet I sent this tweet I tweeted it um one day went back to work or whatever it was that I was doing for the day and then next thing I know. uh 24 hours later, when I woke up the next day, I see that we have, oh, my goodness, all these retweets and well over 160 retweets. We had over 300 likes and apparently some folks from within the Nigerian uh Tech Community started tweeting it they saw it somehow.

A

I'll get the word my network, and uh next thing you know I um literally I had people from all kinds of different countries. In Africa, a lot of people from Nigeria I'm, not kidding I felt, like I, talked to basically to half of Nigeria I'm, yes, I'm, exaggerating so I wrote a joke. Yes, this is a joke fact.

A

I did, though, however, interview well over 100 people, I spent like two weeks, just like interview after interview after interview just back to back to back I, just dedicated myself to meeting a lot of potential new community members, because I was excited to see the huge thirst in hunger for learning how to become an open source, documentation uh engineer a technical writer, as some people call it um I consider us more documentation, engineers and just technical writers, uh because we write, but sometimes we still have to understand and write code ourselves.

A

So anyway, um all candidates were asked the same three questions and I structured.

A

The interviews this way um very carefully and on purpose, because I wanted to give everyone an equal background chance uh from for every background at the same chance and what I mean by that is I wanted people who had both work experience or not work experience to still be able to apply to this with us, because we really love mentorship and mentoring people here at Sync API, which is one of the main reasons why I'm still here happily working at the initiative, just because of how much mentorship really matters to a lot of the people that are main contributors here.

A

Core contributors and so I wanted to be able to um have that same Spirit of mentorship very easily uh seen and available via. You know only asking three questions uh which, as you can see, these questions really allow anyone to be able to contribute to the interview and it's not about whether you're more technically Savvy or you're. More senior. For example. First question: how do you want to grow as a technical writer?

A

I would hope that, no matter how senior you are or how amazing an architect, you might be that you are always aware that we always have to grow. There's always something we need to grow in something we need to learn, whether not just as a personal growth as people, but obviously always in our technical growth. I hope that we never think that we know it. Everything right so I wanted to see uh how aware people these candidates were of their areas of growth, because that's very important uh when you think about in a candidate.

A

The second question is: how would you like to give back to open source if you're selected- and here it is especially especially because this is an open source initiative? I really wanted to make sure that the candidate selected were people that genuinely had the maturity and the uh ownership of understanding that whatever they may contribute to open source Source projects is not about them. It's about how your work can help the community around you and I wanted to make sure that our candidates eventually selected understood that, because otherwise, it's not going to work right.

A

So, third question: uh what project do you prefer to join because, essentially for gsod, we really wanted to finally start growing out our new content, buckets of tutorials, Concepts and tools, and so uh I wanted to know kind of like where people said, because I wanted to place candidates in an area that they would be genuinely excited to work in I. Don't want any candidate to feel. Oh man, I got the boring task.

A

ugh I drew the Short Straw, some people say in I think the US I don't know if that's a worldwide thing or not, but anyway, um I didn't want anyone to feel like. Oh I, wonder if I'll get good luck or bad luck. In assignments, no I wanted people to have a choice in the selection of their assignments, because that's how people can be happy at their work right so uh I would ask them.

A

Do you want to grow um tutorials and Concepts content buckets, or do you want to help grow our tools, content bucket and depending on how they responded, was eventually how they were placed, or at least the six folks that were selected so in the end, I'm super excited that, because of the diversity and huge amounts and I mean huge amounts of diverse candidates that applied, we ended up very easily being able to select six quality awesome candidates, and so we ended up with uh thuli who's, an amazing mother from Cape Town Florence, a student from Kenya karuna students from India Nelson, oh, my goodness, another awesome person from Nigeria and then Anisa.

A

So those two folks, you know both folks from Nigeria, um and he said it's also a mother and funnily enough she's, currently right now and will be in the time of the conference in the United States, because she won this uh place in a master's program in the US, so we're very proud of anisap and uh well we're proud of all of them. Of course, don't get me wrong anyway. Moving on and amazing prateek from India, pratik and karuna are just absolutely hilarious.

A

I love them both and um we love them all they're, all just so amazing and I, really like that. uh They've really done their best to uh learn and start contributing uh to the open source community, so I feel I think we're all very lucky to have their contributions, uh and so yes, uh that tweet did perform very well. As you can see, we had over 45 000 Impressions. It was unexpected uh over 2, 400 engagements uh and I mean I.

A

Guess that's why we had over 200 applications right and we over 2 500 people interacted with it all right. So, let's move on and actually talk about what changed in our information architecture. So, as you can see via this mind, map this is the new information architecture that we now have thanks to our work this year. So far now we clearly have content buckets defined with different purposes. Right we have Concepts tutorials guides reference and tools. uh What do we have in reference? Well, our API spec, of course, uh tools.

A

Well, we would put all of our tools there. You know. Eventually it won't just be you know. Modelina or you know, the generator tool is what we're currently working on 4G sod. uh We want to add the CLI there's. You know we want to add all of them, uh but you get the idea- uh we're very excited about this because now there's a clear understanding of where to find information as a user depending on what your question is.

A

What your area in your question is, for example, Concepts is going to be used for defining and explaining visually with diagrams the new diagrams that we now have each API spec term. So we will have a page to Define producer, a page for Server Channel application Etc, so one for each one and there's actually a couple of them that have been live even since, before the conference started so I you may have seen them some of them live already, but we'll talk more about them in a moment and also tutorials.

A

We already had a tutorials, you know content before, but we didn't really have that content bucket, specifically outlined in our website for our documentation. So now we do have that and we ended up actually majorly rethinking and restructuring the tutorial section. This year, at gsod and I'm so excited to share with you what those changes were in just a few, more slides, moving on to guides, so a guide is different from a tutorial. A tutorial takes you from point A to point B.

A

For example, you know I have my computer in front of me and I have no code written in front of me, but at the end of this tutorial, I want you to walk me through step by step how to build my for uh first uh react: App application. You know whatever something like that verse. This is a guide, doesn't actually guide you step by step into building or doing something.

A

At the end, a guide is instead um more of a visual, a bigger picture kind of uh document, a guide teaches you, the capabilities and the features of your technology. Let's talk a little bit more about that, because I do find that often that dust trip writers up and not just writers. uh You know product managers in the world of Enterprise absolutely get confused constantly about the difference and you see it in their documentation. Whoopsies.

A

Definitely engineers get confused about the difference. Writers get confused. You know this is a problem all around. So let's talk about this okay Alejandra. Can you please help me understand, really the difference between a tutorial and a guide? Well, you know what I'm like to always explain this by talking about grilled cheese, sandwiches, yes, I honestly believe that a grilled cheese sandwich will be what can best help. You understand all right. So, let's start with the tutorial.

A

I did say that a tutorial was step-by-step instructions for going from point A to point B, for example, if you say Alejandra, please write me a tutorial for how to make a grilled cheese sandwich. I need a tutorial here. You go so I'm gonna write out. You know every single step, I'm going to tell you, you know, take out all of the ingredients, and you know if this was in a PowerPoint slide.

A

I would actually list out every single ingredient, but you know trying to keep it succinct to the point here right then the next step would be grab. You know maybe a frying pan uh turn on the stove, oh butter, the bread slices all right, you know, put the cheese slices in between each bread and then oh, you place that over the frying pan until the cheese melts you know, and then you take it out and at the end of this tutorial, I have a completed amazing, delicious grilled cheese sandwich.

A

So if you were to come to me instead and say but Alejandra how about a guide? Well a guide, yes, what would be a guide for grilled cheese sandwiches? What would the difference? Be? Oh, okay, that's a really good question. So a guide for grilled cheese sandwiches would instead explain at a high level so again big picture here at a high level, the capabilities and the features of a grilled cheese sandwich.

A

So what is the capability or what is a feature of a grilled cheese sandwich? uh Okay? Well, it's a grilled cheese sandwich capable of being cooked with different tools does. Is it? Is there only one tool that can be used to make a grilled cheese sandwich? Well, no, of course not you know, uh maybe you don't want to use the frying pan. Maybe you have one of those fancy sandwich. You know what I'm talking about those little fancy sandwich, Contraption thingies, clearly I, don't own one myself or I would know the name for it.

A

Sandwich maker I, don't know so. Okay, we agree. There are different tools that you can use to make a grilled cheese sandwich. So you know that's a capability, I guess of the grilled cheese sandwich.

A

um What are some features? Well, you know, can I add more than one kind of cheese to my grilled cheese. Oh yes, you can hey. You want maybe a triple cheese sandwich there. You are hey, you know what can I have ham? You know. Yes, we can absolutely add ham to her grilled cheese sandwich. Maybe you're wondering though okay Alejandra, I, don't know. If you have this feature or not, but this one really matters to me. I need to know, will you be adding a feature to make grilled cheese sandwich with bacon?

A

Oh, my friends, I have good news for you today. That feature is available. Yes, it is. You can absolutely put bacon in your grilled cheese sandwich all right boom, so we have a guide now for grilled cheese sandwiches and we have tutorial for making a grilled cheese sandwich so now I think okay A little bit of maybe a lot of fun, but you know what I think that now it's definitely visually uh a lot more uh understandable.

A

The difference between what the purpose of a tutorial is, what the user needs from a tutorial versus what the user needs from a guide and you're welcome for making this fun moving on.

A

Thank you Doc's homepage, before and after so I'm excited to share with you that now our current Ducks home patients completely different from the way that you know this looks like you know, even just beginning of this year, I believe or last year. uh As you can see, we didn't even have a home page explaining to you as a user. The different learning paths that you might choose to take depending on your goal.

A

As you can see, we had a getting started section that seemed to be separate from the tutorial section, and then there was specification and something called Community which had tooling inside of community. It didn't really make a lot of sense versus now. You know we have awesome amazing, five, uh clear content buckets, and this would only be possible again thanks to our jassad interns, uh as you can probably remember. Potentially, hopefully, the documentation menu changed as well.

A

So what you're, looking at you know at the top is what we currently have versus what was there before, as you may or may not have noticed. Potentially, though this is a little bit harder to notice unless you're, like really like testing things in our website, constantly like some of us are, uh the interaction also changed. So uh docs is unique in that.

A

Not only can you hover over it to uh get the sub navigation, but you can also click through directly to the home page of the docs by clicking on the word docs, the docs item menu, which is different from you, know what we have in tools for example or Community, um so we have a unique uh interaction functionality there, uh which of course was necessary because we actually have a home page for that documentation page. You know it's inqpi.com Docs.

A

Now here's the exciting changes coming up for the tutorial section, um as you may or may not remember. uh Now we have an overview that details the purpose of each content bucket and then we have what makes more sense our quick start, which in this case is our getting started tutorial and currently you know we had. You know, at least at the time of my recording this, the uh street lights tutorial street lights, interactive tutorial as well.

A

Well, at some point in our community work, some of us uh well Lucas uh had an idea, and he says: oh, my goodness, you know what uh what if instead, we finally uh kind of divide this into four main ideas, four main things that people can do with async API and the four common things that people ask us. You know how do I do this. So, of course, uh if you are active in async kpio uh with the syncope already, you might already know that those four top things were here.

A

They are creating any Sync, API document, validating that document, generating code and, of course, validating the code, kind of messages, slash events now I had and a lot of the folks in the community honestly beforehand already for a while kind of noticed that these changes needed to come. So we were definitely very excited uh when Lucas proposed dividing it under these four new uh ideas and more on that to come.

A

We also now have, of course, diagrams which we did not have before, and so now you kind of see what we you know have in the markdown. It's basically markdown generated uh diagrams, and then you see what it looks like when it's live on the website. It looks awesome, and so now all of our concept, Pages at least start have at least one diagram each, although most of them have two now I know.

A

Some of you are wondering, hey, you know, what's left, for you saw 2022 well right now we are still you know, uh making those changes to the street lights tutorial and we have all of our lovely interns. You know with a lot of pull requests out for New Concept Pages there's.

A

You know they're working on feedback, and we have a lot of folks that that are also working on tutorials and so at the end, what we're going to end up with uh the goal being at the end of jassad, which is should be end of November, perhaps really December at the most uh we're gonna have not just the overview and getting started which we already have, but now instead, following that, we'll have tutorial for creating Sync API document, validate a Syncopy document generated code and validate code messages and events.

A

And, of course, we have so many more things we want to add eventually, I want to add another subsection and tutorials for protocols, because uh we know that we want tutorials asyncypi with Kafka and websocket, etc, etc. But at least we just saw 2022 this year. Now we will have these clear actions that a user can learn on. The tutorials will be much more tailored, so we're very excited about this, and thank you Lucas, of course, for the Amazing Ideas.

A

Now the goal for Concepts should be that at the end, we want to end with not just server and producer which are currently live. As of you know, this recording, but we also want to end up with ideally 90 of the spec terms, if not all so at our minimum goal is to have server producer, consumer protocol channels, application and message, but our stretch goal is to also have bindings, so that would be all the spectrums defined and Illustrated uh big.

A

Thank you to all of the folks who have been also reviewing and giving amazing long detailed feedback to all of our work for jisad, because without those reviews and without that feedback we wouldn't be able to eventually move this to get merged and live to help our community.

A

So, as you can see, um there's been a lot of work done. uh You may remember, we have our six lovely jassad interns. uh They had to learn literally everything from scratch. All of these folks had never worked with async API and they had never worked with a vendriven architecture, so very very much so all of this was new to them, so I'm personally, very proud of how they undertook the huge learning of onboarding and having to process so much information.

A

They also onboarded right before we made a lot of these major information architecture changes uh both with the help from design contributors like Mrs, turko or developer contributors like masiak and I, believe akshat might have also made some changes uh and um and not that it was specific, but he, for example, helped add the feedback card which is just what we needed for our documentation.

A

um So yes, besides, we saw it. We had contributors from design. We have contributors from docs. Yours truly, uh not just me. Of course, we have a lot of people contributed docs, uh but anyway you know what I mean you know you know and of course a lot of uh country contribute from development as well.

A

um uh We are very uh excited that we were first of all selected for just saw 2022, we weren't sure, because of course, it's hard competition more than a hundred, uh if not more than 200 people apply to decide at Google itself.

A

You know us initiatives in open source, so uh definitely uh thanks to Google for selecting us and uh the grant money that we are now going to be able to give uh to our jassad interns at the end of The, gsod, Internship uh and I'm very excited that we're able to give them something for their contribution.

A

um So yes, um I, hope that now you folks uh are a little bit even more excited to contribute to docs next year my dream, my goal is to apply to jisad, 2023 and now I want to pitch them. Instead of a information architecture, flip I want to pitch to them that we should just finally enhance ourselves and build our async API learning platform, and so that's what I want to pitch for next year.

A

So if you are already excited about what we were able to do with our lovely contributors for a sync UPI Community uh during the Assad program and you're excited to see what could happen next year. Well now you kind of know what we're thinking about we're thinking about a learning platform. So if you want to volunteer or help Mentor like now, it's the time to reach out to me, don't wait till the last minute all right! Well, that's it! Thank you.