 We're going to start by saying that it's a both, both of a feather, for those who are not familiar. I didn't bring pretty slides, actually, because I hope this will be more of a discussion. And I wanted to start, so this is all about Zephyr and Zephyr documentation. So I will actually start with a question, which is who in the room is using Zephyr? Okay, who is contributing to Zephyr? And was a maintainer, maybe, to some, yeah, there we go. Okay, so that's, and are we good with the slides? Or, hey, so I should maybe quickly introduce myself. For those who don't know me, I'm Benjamin. I work at the Linux Foundation as a developer advocate for the project and Jack of all trades. One thing that I do, we try and make sure that our documentation is looking good, that it's helpful for all the personas that and all the kind of people that might get involved with Zephyr. First time users, first time contributors, people who use Zephyr on a daily basis, like maintainers, et cetera, et cetera. One thing that we did and it ran for a bit of a month is, and I'm making sure that you get a chance to flash the code, if you didn't have a chance to take the survey just yet, we tried and asked the Zephyr community at large, the things they like about the Zephyr documentation to see the things that maybe could be improved. And so some of the insights from this particular survey are gonna feed, I hope, the discussion today, but also your feedback will be very, very helpful. So yeah, it's been, well, pretty much exactly a month, I guess, since it went live and we had, to my surprise, that kind of, it tells something, I guess, about the size of the Zephyr community, but yeah, we had over 80 respondents. Most of the promotion of the survey, you may have seen it, was through the Zephyr Discord, the Zephyr social channel, so the feedback is probably biased one way or the other, like it's definitely like the Zephyr crowd, sort of by definition, we took the survey. But yeah, some questions that we asked, like nothing specific, I guess, there, but I'm trying to understand better what are the kind of people using Zephyr, their experience level, because you suddenly have different expectations, whether you are a, like yeah, a hobbyist, that just getting started with hacking with Arduino and looking at what could be next, or whether you are actually a Google or an Intel building embedded controllers and whatnot, like we saw in several keynotes at the event this week. What you like, dislike, what you feel is missing, and some of the themes that emerged, and some of them I'm gonna dive deeper into is things like searching for information in the Zephyr documentation. For some people, it's actually working very well, for some, not necessarily, and kind of related people finding it hard sometimes to search for, hey, I wanna know whether my particular board supports these or that in Zephyr, like some kind of questions are hard to get answered when navigating Zephyr documentation. Navigating actually is something else. Several people commenting on the fact that if your thing is browsing more through maybe the API documentation, you might find lots of information there, but not necessarily the pointers that would take you to actual concrete examples or actual code and like having those bridges. I mean, there might be some that are missing, so we'll try and double click on that. Lots of people commenting on the fact that we have lots and lots of great samples, most of them up to date really helpful to get started, but maybe too basic in that they only cover like a particular feature, people asking for more like end-to-end, more comprehensive samples, tutorials, going all the way potentially to like more best practices. Some other things that I think we'll get to discuss maybe more towards the end, but some people do care a lot about having PDFs and having something that they could download offline. I mean, not lots of people, but this is certainly some useful feedback there. Some people also being like, hey, I'm not a native English speaker, what's the story there? So in a nutshell, I could have almost like I mean, most of the keywords there are actually verbatim feedback. Many, many people are like, this is good, your stuff is up to date. It's very, very extensive. It's honest, which I mean, yeah, I guess there for being an open source project as opposed to maybe some like commercial solution, whenever there's an API that's just experimental and that has some shortcomings or some, I mean, it's usually actually right there in the documentation, which by the way, the documentation lives with the code, which people really value because that helps with the up to date, I guess aspect. There's more than just generated documentation. People appreciate the fact that there's many, if not all the maintainers of all the areas of this effort take the time to add actual like text and human written architecture, descriptions, diagrams, et cetera, the samples. It's like pretty much every other respondent who says, hey, your samples are great. Now to some of the pain points and they're like, I wanna dive into some ideas, open print storming on things that, I mean, that's some of the pain points that people sort of commenting on. Some are actually already in the process of being fixed or already fixed. So I wanna dive a bit into that too. Until recently at least it was sometimes hard to get like from a search engine, such as Google or anything really, like trying to search for Zephyr information, you would land on Zephyr 2.3, whatever old documentation which is not necessarily helpful. The internal search, like when you're already in the documentation, this is something that some people are complaining about like the accuracy or the sort of the ranking of the results could be better there. I put that as a pain point, like the fact that people want more tutorials, more best practices, it's only something that came often and I really wanna discuss about that. Some differences like in some areas, some boards would be better documented than others. It's just wanting to surface it as this is something that came, by the way, I should mention that the slides will be online and towards the, like in the backup section of the slide deck, there's all the anonymized version of all the feedback with all the charts, et cetera. I encourage everyone to check it out and we can always discuss offline if you wanna get involved or have thoughts there. There's also I think something that's important, especially with the crowd we have here today, the kind of feedback that's more geared towards people who actually contribute to Zephyr and that may be in a position where they are writing documentation. Some things that could be improved is that setting up the local build infrastructure for the doc specifically might not be ideal. At best, it takes time to build the documentation so things could probably be improved there and one thing that often comes and not only in the survey is architecture diagrams. We have many of them and many of them, like if you are a contributor, you probably know that some of them are like PNG files that are baked into the documentation and like you have this nice architecture diagram, sorry, from two years ago, which you would really like to update for, because I mean things have changed, except that you don't know who came up with this particular PNG and you would have to be created from scratch, which is not ideal either. All right, so yeah, some of those things are actually already fixed. So just as an update to the community, I guess, I just wanted to make sure that you know and maybe you've experienced that nowadays when you search for some Zephyr, how to create a thread in Zephyr sort of stuff, hopefully the top one, two, three results will always bring you to the latest version of the documentation. So this should be much, much better now. One thing that we did as well is what you have at the bottom right of the slide is that when you are on the Zephyr documentation itself, we're not listing anymore like pretty much all the versions of Zephyr since day one, we only list the ones that are effectively supported, which is the current LTS plus the past couple releases and that should also help with the world search engine indexing situation. Yeah, and like that's just a way to show you that until, oops, I almost fell there, until about a month ago, you would have, yeah, people searching for how to create a thread with Zephyr and they would be taken all over the place to Zephyr 2.3, 2.4, 2.5, whatever. Now hopefully when you search for information you get taken either to only Zephyr latest or to LTS if you really care about like LTS specific information. One thing as a sort of a segue into the other topics, one thing that I've been looking into these days is, and this is where I will effectively when I open it up to you all, there are some more modern themes and like documentation infrastructures out there. We're not necessarily changing everything in terms of how we do things. There might be some low-hanging fruits. One thing and I actually wanna show a demo is a different theme for the same documentation infrastructure that we use, which is things, the immaterial theme, which would potentially bring us interesting things in terms of having editable figures, having improved search engine, having potentially better rendering on like tablet or like mobile phones, which we don't necessarily always have with the current infrastructure. So yeah, just actually a quick demo of how things look like and maybe starting with sort of, blue blue, sorry, just, yeah, like, so that's Zephyr documentation today. If you were to search for something like say QMU you would get the results on the right, which to my point earlier and to the point of some respondents, this might not be the best sort of set of results, because I mean, if I only search for QMU, I probably want maybe, I think this result actually, the one that will explain to me how to develop on top of QMU, but anyways, that's how things look like, generally speaking, with Zephyr, the other theme that I mentioned, I think could bring interesting and a quick demo of how things look like for this guy. So I didn't spend time to use the fancy Zephyr purple and whatever, it's pretty much the stock colors there, but searching for QMU, this is kind of a different story. I think it makes, but I would like to hear from you. I think this makes things slightly better in terms of identifying other search results really relevant to what I'm looking for. I only search for QMU, but it's showing me way more context in terms of what are the pages that match, but more specifically, what are the different sections, subsections, and yeah, that can actually help, I think. Another thing that the theme does as well, is that, and we have a demo right here, for the editable diagrams thing, like if I were to be interested in having some kind of sequence diagram somewhere in the documentation, it could actually live right in the documentation, just using the mermaid.js framework. So what's that? So you can, yeah, you could have an inline sequence diagram and wherever comes after you and needs to edit it, well, it's there in source pretty much and you can have state diagrams, which to some extent we already have with GraphViz, some of those diagrams we can already sort of have in Zephyr, but I mean, the mermaid goes way, way further, but to some extent switching from one theme to the other might be disruptive to the community, so I don't know what you guys think, like even navigation wise, you may have realized that, and going back to the actual Zephyr thing, I kind of like the fact that the table of contents, which by the way is not ideal for the project, here when you use this new theme, and if I were to look at memory protection, this is sort of the really high level outline and table of contents, but then on the right hand side, you have the one that's more geared towards and focused on the current page that I'm browsing and that might make things easier, including having things that are API related, they would show up slightly differently, so yeah, maybe before I jump into all the topics, any thoughts, any feedback there from what you see or any, yes please, so there's a mic right there or just speak loud and I will just repeat your question. Yeah, I tend to agree, I think there might be different, so the question or the comment is that to some extent it might be kind of weird that you have the outline split part on the left, part on the right, there might be ways to tweak it, but yeah, I agree, I actually was confused at first, and that might not be the best way to present the information, yes, yes? Maybe if we think that changing all of a sudden would be disruptive, maybe we can do a new documentation beta and host it like this version simultaneously for people to try out and then get feedback. Like A-B testing, yeah, no, I thought about that just before the, yeah, that would be one way to do it, yeah. Yes, yeah, no, thanks, that's good feedback, yes Dave? When you did the search, that's one of my big problems with the Zephyr documentation is the search because like you said it tends to throw up a lot of stuff and it's almost easier to go into Google and search that way because Google indexes it better I think, but on the CUMI one that you asked in particular, I'm kind of interested in figuring out how it like figured out running CUMI directly, running CUMI via Ninjas, are those sub-tech topics inside of Zephyr or did it somehow? So yeah, so with unnecessary going into all the details which I don't understand everything in the Sphinx framework but they have their custom, definitely non-Google base, like when you build the documentation, it builds an index based on like page title, page headings which gives potentially a score for each and every keyword and so the fact that for the, within the application development page there are several headings and several like sections that have QMU in them so that contributes a bit to having this page ranking a bit higher than others and then inside the sections themselves, the keyword shows up again so that that's why that it ends up showing that high but quite frankly, I don't know why this one is number two and then why the other one which doesn't seem to have as much matches shows up number first so. It's a quite sorry. Oh yeah, yeah actually you're absolutely right with this, yes, yes so all the matches there are the ones that are ranked 50 or something and 50 is the maximum with this particular implementation of the built-in index so actually that's one great segue into one open question to you all. I was playing just before with, I mean yes we are an open source project but I think we wanna provide a great experience to the users. One thing I was playing with earlier and that we could really really easily include into the documentation is and just ignore by the way the ads. Like this is the, there is this Google thing where you can have your custom Google search engine that's just tailored to your domain or subdomain and then it would give you whatever you would effectively get from Google proper except that you can really easily host it on your website so if I were to search for QMU and we could very well have this particular search for baked right into Zephyr and get results that I think are way better ranked or at least like they feel like they are better matches but I mean implementing that means that either this needs to be something that, I mean we all agree is a good idea and we baked into the project and or this is an option like we still for Zephyr.org we still like use the built-in index but anyone who builds the dock locally could enable the feature like I don't know like if people have thoughts there. One thing also before people maybe comment on that is part of the reason that the results there might not be that helpful is that historically like if you look back in time at some point there were some tweaks that were made cause some people would like, let me just show you actually what I mean by that. So just speaking this randomly but searching for STM32 depending on your profile or persona you might or might not want this to actually show you boards from STM32 and it actually probably want cause the boards will be like very, very, very penalized by our built-in search engine by design cause at some point back like five years ago people were like no when I look for GPIO I don't wanna get results that will tell me that whatever NXP board or whatever STM32 board as GPIO I care about getting the deoxygen dock for GPIO but that was people like five years ago that pushed that kind of change which is why like yeah indeed when I look for GPIO it will likely be more like the bindings and or a deoxygen stuff that's for the first but that might be there might be some easy fixes there. So yeah, thoughts on the Google thing if you get the mic that's even better. Good, I'm working four years with Seth here and first I want to say is a lot of improvement in the documentation and I was also teacher on a university for control science and was a very difficult topic and what we recognized is so for those I think for all those guys sitting here it's not so difficult to find the topic for me the difficulty was if there is a new philosophy and device tree is one of this which we tackled somehow yeah I think we are still not on a very professional level here. The other topic is unit testing what we want to tackle now in the next time and probably we want to contribute in terms of a tutorial then yeah. But for these things you know it's somewhere there you see some piece of code but you do not understand the philosophy. And if you do not understand the philosophy you need to start from scratch and if you start or this is at least for me my brain is old yeah and it's also small the best way I learn is if there are 100 things people do not tell me about 90 they tell me about 10 things because 10 things I can keep in mind maybe yeah. And this is really a challenge in a deductive way it's about the tutorials and I think this is the challenge here and the question is how we get started with this and what we think when we now try to do this unit testing so we found the Google guy he said he will help us in this court yeah. And what I usually do or sometimes do if I have time I write my own paper yeah. So I write an eight-pager and then see yeah does this match that. Well contribute it back to the project like. And this is what we would then use somebody if we write this down the next step is is this correct how we extracted it yeah. And they say yeah you understood this not but probably this is the process for this. So as long as we are newcomer we can do this task once we know it and maybe it's too late for us we need a new newcomer then yeah. And but I think to summarize this I think the difficulty is it is very complex it's very powerful but for the newcomer you need to start with a subset which you say let's start only with these things we explain it and now here are the samples yeah here are the samples run it so when you internalized it yeah. Then these are the next 10 topics so I explain it and now these are the samples yeah. Well actually so was there another question cause otherwise I would yeah please. Not a question just comment on the search stuff at least the Google one seemed much more usable than Alphabetic which was only useful by chance because of application yeah. And I had a second thought what was before the Google search what was shown before the Google search stuff. So what was that? What was the slide before the Google search? We talked a bit about the images like the figures like diagrams that you could maybe maintain as code. Good wasn't that anyway. Anyway that's fine one thing yes please right there if you one thing that could be also a challenge with the Google thing which I mean I would love for us to have that in the documentation. Right now the index that we have might suck to some extent but everything works offline. If we were to rely on like some sort of server side it doesn't even have to be Google but server side search engine then people wanna run the docs locally might be in trouble. That's a great point that's something actually I did on the train way here is I built the docs on my Sandy Bridge laptop I don't know if it takes a lot longer than you'd expect. Is it? Well you know it's an old 10 year old machine. Anyway very banal question I like the new theme so far and I'll also I mean it's an attempt or like just showing what yeah. A very banal question how's the dark theme for us night owls? Good question. Let's just look at the actual like them. Yeah cause that's I really didn't tweak. Give me a minute there. No worries. There. So that's not Zephyr that's the upstream sort of demo of things in material but that's I think that would be a better way to get to give you a sense of how things are going there. Yeah that's nice and readable. I also kind of like the better the bit of the better categorization on the right with the API specific stuff. Cause I found it was pretty straightforward that you know left you have the general sort of topics in the main documentation and right you have the page specific stuff so. Okay. Give it feedback. But yeah doc theme is actually pretty important. Yep. Do you have a comment? Just one thing and I'm completely possibly this off the point but it feels to me that like if you have a search like a free form search on your website or whatever like then it's either has to be has to work very well or has to be very simple. I see what you mean. Cause you're going to ask simple things anyways. Yeah. Maybe have a search for just titles and direct for everything else to Google because that's the best we can have except maybe you know something like chat GPT or stuff. Yeah no like yeah I got your point. Just my feeling like if I go in search there like it's often frustration and you feel like you cannot find it so that's that's bad user experience I think. And for what it's worth and that's probably actually your approach to many people said that use the code look like I mean they would just like as a beginner and I have a few slides on that you would use the online documentation but as soon as you're like starting develop to develop with Zephyr well you just grab somewhere in the code and that's the doc. Yeah for better or worse. Quickly and I think you sort of hinted at the fact that you were building the docs for those who care about like getting better experience when building the documentation locally we are slowly looking at improving things there cause even if you have like really good machine can be 12, 15 minutes to build the doc from scratch locally you do a small change and it might not be that well managed in terms of doing a nice incremental build so even if you just change a line it will be another 15 minutes. We yeah we it's working progress there just something that I wanted to share especially maybe for the contributors and the maintainers things that you might or might not realize and it's either you see it as a challenge or just at least a fact. People browsing the documentation and using the internal search engine what do you do they search for? They don't necessarily search about how to do Bluetooth audio broadcast or how to do low power on ARM Cortex M7 blah blah blah they seem to be at least like in the top search results they look at pretty basic concepts right and so actually for some of those keywords and as we saw to some extent like QMU is like top 10 keyword that people search are we giving them helpful information and the best results that we can maybe not kind of related and I think do I have yeah the next slide is also kind of related it's not perfect cause and that's my next topic but looking at what are the top viewed boards in the documentation it's very much maker or DIY oriented right and that's something to have in mind like it's whether we like it or not like the community is just so big that all sorts of crowds are using Zephyr or looking into Zephyr including people which is like yeah they're gonna run Zephyr on Arduino Raspberry Pi Pico sort of stuff but this is also to be taken with a grain of salt in that for those who are like closely involved in the project you probably know that we don't we dropped again another Google product the Google analytics support in the documentation so as we look at making the documentation better I think it's important to have access to good and accurate metrics this is definitely accurate cause I actually went and looked into the yes yeah just wanted to point out that is in order right of what is most accessed not the top 10 in order the previous slide sorry say again that like the number one was Air Pi Pico right so it's yes yes yes the number one access board is a board but based on cause we don't have Google analytics anymore based on the hits on the server like on the server side I would look at the logs of our Amazon S3 buckets blah blah blah and this is based on like how many times people like fetched this particular URL it might not be unique people like but I kind of I'm fairly confident that and that's why I didn't put like numbers in front of them but ordering I'm pretty confident but I think it's interesting that the first one it's a board that is contributed yes there's no it's not officially maintained by yes yeah and so is probably there might be others somewhere else and it's probably not very used for commercial product either so sure but that's a great opportunity for attracting new user have imagined it's popular and it always gets used with the Raspberry Pi SDK which locks the software into that ecosystem I do wonder how many people end up there by mistake and I just go yeah and that's part of the thing that are hard even harder to know and to tell cause yeah I'm really looking at the hits on the server side it might be just like bots it's not like people it's not necessarily people who actually open the page on their machine they've just Googled Raspberry Pi Pico and if Zephyr is the second link there yeah but that's goodness though that should be a good way for us to bring even more people into Zephyr but yeah I thought I would share as a sort of an FYN I mean don't you have a referral URL in the logs like where the people are coming from yes I can we can and these are without referral URL these results are without the referral it's all hits on this particular URL okay so I mean the question about like if the people are searching just for Raspberry Pi Pico or they're actually interested in Zephyr yeah so for those who are into SEO and like web analytics like this information is not available anymore like for the past couple years like you would know that they come from Google you wouldn't know the actual keywords sadly yeah or maybe you guys can try like if you want to try and like what are the kind of keywords that would give the hit um yeah sharing so by the way thanks for the engagement there that's super super cool yeah a piece of feedback more maybe for the maintainers and contributors but I felt that this particular one is like we're gonna click on the link and it really I think this person provided really useful feedback for some high level pages like PWM it would be great to be able to navigate from the API documentation to samples that are relevant I mean the sample is probably easy to find but it let's click on the link like there's so old theme oh yeah it looks doesn't look as nice maybe but yeah I mean the PWM API documentation seems pretty pretty complete but pretty bare bones also to some extent like it it's true I think that it could be linking to samples in the code base and or like I mean this and PWM is kind of those features that which possibly every other user and developer will be will end up using anyways and what that person said is that either like sending people I mean sending me to the code samples would have been nice or even having some kind of code snippet which I could literally copy paste cause that's what I do as a developer full honesty here is what the person said and yeah that's yes Mohammed yeah take me right in the yeah the right place in the yeah yes yes one more comment on the the search functionality so maybe as a sort of in-between solution between going full you know online Google search versus you know the the flawed current inbuilt search is maybe adding metadata to the to the the actual files such as I was just quickly checking the Sphinx doc and there seems to be a file-wide metadata and then chapter 10 1.10 so maybe you can specify tags like you said with Qmo you can say okay this this document has Qmo this mentions Qmo x86 you have a list of tags and the search function would prioritize tags and after that default to the previous current search functionality which would kind of maybe bid I think it would give a lot better results yeah no that's a good point or even like yeah indicating that this particular thing should never ever match this particular keyword although maybe the search engine would have tended to yeah nuts that's alright so we are actually gonna run out of time pretty soon search I think we covered kind of like another in-between solution could be so we could improve the local mostly javascript based search engine that Sphinx has we could only look at Google and there's also other service like Apache solar sort of stuff but that would require hosting an index somewhere which again I'm not sure is something we want to do because you want to sometimes browse the documentation when you're on the plane and that's yeah so again running out of time but all the topics we covered including search discoverability like what are the kind of boards that I could use that support search or such feature to samples tutorials I would love to hear from you in the few minutes we have left if you know of any other open source project that's kind of like in the RTOS or IoT space anything that they do particularly well just I mean let me know because that that'd be great I think for example right OS is pretty good or at least better than us to some extent at making it easy to find what other boards that are supported in their ecosystem and making it look prettier to re-note as this nice dashboard which helps at the discovering the features also of the hardware I've been told and I've seen in the feedback in the documentation that free RTOS or ARM with the CMC's RTOS they have really nice intro tutorials with more like architecture guidelines etc. yeah please like of course we are running out of time but I'll be sitting around I think this is important to take yeah good feedback from and good inspiration from others and yeah that's pretty much what I had did we have anyone online with comments or questions we didn't okay so yeah I mean let's take the rest of the conversation to the reception maybe all right thank you very much for the engagement