 Welcome everybody, this is the meeting of the Jenkins documentation special interest group. Let's take a look at the agenda and then what we'll do is review the agenda then walk through the pieces that are on the agenda, sharing my screen. And here's what I've got report on previous action items, a brief point on brief point on collaboration with other special interest groups. Let's talk briefly about the Jenkins rest API on swagger hub. Then we've got a demo proposed for the plug in site to get hub integration. Oleg I think you're our demonstrator on that right. Yeah, show some demos today. Great. Excellent. We've got a topic on the community bridge sub project for docs that should be discussed further. And then in usual pattern I'd like to go over the stats just to show that hey we're keeping track of things and we'll talk about how the project how the documentation project is progressing. Are there any other items that need to go on the agenda, either from you Oleg or from you Markey. Anything for me other than maybe to add about the elections process and the new documentation officer role. Oh that's a very good one right governance board. Elections and documentation. Was it the title is officer. Yeah, good topic. Great. Thanks. Okay. All right. And let's let's proceed from there. So previous action items. I've started the poll request on docs project ideas. It's a large effort. I will continue that it is not ready for review it's not ready for merge yet it is ready for review thanks Oleg for first review, much appreciated. If I get a summary posts, I will mark to post I will post one to the mailing list today when I send out the agenda from this meeting. Any other action items that I've missed in the, in the list of action items. Okay, the next topic collaboration with other special interest groups. One of the topics Markey had been documenting the infrastructure anything you'd like to report there in terms of what you've learned and experience so far. I can say that it is a scary place to look at it is so wide and so vast. And that is going to take a considerable amount of time. Okay. So on the configuration is code plugins. It seems like that's that project is making rapid progress. Anything that the doc sign needs to be aware of there. Well, as every way we will appreciate any contributions with regards to documentation. I would say that the documentation is pretty good. There's a lot of opportunities to improve it to add more demos. There are still some missing features surprising the rest API. I guess we will get to the next topic. But yeah right now rest API for competition as code is a documented at all. The rest API needs to be documented for configuration is code. Yes, so there is a new before they pick it for that. Well, I'm not sure how much it's neither friendly but definitely need to do something about that. Interesting. Yeah, so I wasn't aware of a rest API that's that's cool. That's good. Okay, thanks. Yeah, rest API exists. Yeah, even CLI exists is also not that documented. But yeah, it's something we could improve there. Thank you. So and you indicated the rest API may not be newbie newbie new as newbie friendly. Well, it's newbie friendly just requires some time to process it because basically you need to go through code and extract it from code. It's a single class. I will put the link to the GJ ticket later. Or to get half issue, but yeah. Something we would help if somebody is interested. Okay, great. Thank you. All right, so that that could also be listed as one of the project ideas of things that we would take others help in happily. Anything else on collaboration with other six. I don't have something specific. We have some folks to make documentation in Google some of the perspective. So yeah, there is usual demand to have some clarity about contributing violence and other things are basically nothing to do in terms of feedback. Maybe we'll do another round of documentation improvements before GSOC 2020. So we did a lot into 719. But still, that would be a lot of fun. Great. Thank you. So that we discussed two weeks ago the possibility of hosting the Jenkins rest API on swagger hub with a proposal from a boot. Sharma. I created the organization and ask smart bear by email if they would be willing to host it for us. We are now very near the end of our 14 day period and no response. So, and I have not posted anything on my own. I'll refresh that request to smart bear. Mark to create one more placeholder documenting the idea was document the notify commit API as a very popular API. Yeah, I wonder where we can get a response from them in Twitter. Good, good question. Good suggestion. Yeah, because if common channels don't work with usually works. So yeah, maybe something we could do. Next week. Oh, yeah, I can. Yeah, I can try it today. I've got got. That's a good idea. Very good idea. So then I think we're ready to talk the plug in site to get hub integration sub project or like would you like to go ahead and give an overview I am so thrilled with this I like already what two plugins I maintain have benefited significantly from it. Thanks a bunch. Okay, happy to do that. So yeah unfortunately we don't have as big on the call. So if you stop scrunchie, I will do scrunchie and so full disclaimer. The work I'm presenting has been done mostly by as we need connection who is one of Jenkins contributors and who contributed a lot to the Jenkins resources. And there was also a lot of from all the other means is infrastructure. So basically I just did some report and facilitation in this project. So yeah, it's not just my work. But yeah, I want to share this story because it's really important to the Jenkins community, especially to the documentation specialist group. If you take the 100 plugin, for example, let's take the new plugin. Just, you can see that the most of the communication is available on the week in our base. And if you navigate to the key, you can experience common issues like loading time, etc. The layouts are not always good. So this layout is all that's okay. It might be a bit obsolete. There are some working components like message from Python on Jenkins and this program is deprecated but now we will move to the plugin. And in many cases, documentation is basically available on the weekend. In Jenkins, we have a plugin portal with plugin Jenkins.io. And then you can find the documentation also. So for example, Jenkins plugin sites, many plugin pages, they basically redirect you to a plugin portal. And here you can see basically the same page because this plugin site retrieves information from the media. And it was a default behavior for years. And unfortunately, for many plugins, it doesn't work as you may expect because just a weak key was quite difficult to use. So in many cases, you can see pages like that. The plugin provides a tool and started live, see the condition here, change look here. So get up, get up. And this is one key so that also other use cases, for example, for integration as well. Here, that is not the communication at all, because there is no metadata. So this is an issue for Jenkins users because they need these pages, these pages are from default sites and basically they can see nothing. They are simple contributors. It's really difficult to use. For some time, we had an extremely difficult capture there. As far as I know, now the capture is removed, but still contributing here, it's quite complicated. There is basically no way to prioritize pages from vandalism. There is basically no way to have code review for changes proposed by others. And there is no recognition or whatever. Yeah, one of the answers to that is documentation is called and this solution which is being used in many plugins. So since Mark said about his plugins, let's go to the plugin. Okay, so here you can see some documentation on GitHub. So what is an advantage that anybody can adjust it with documentation by clicking this button? Anything, can you think, preview pages and then send it to the question so that one of the maintainers will review it and integrate it. And after that, the content lens, plus you get your contribution, you also get referenced in the change logs in the case of major changes. So it helps. I'm not sure, do you have any documentation changes in the change log? No, because I only just barely implemented the first change. So there's only one, it's published to the publisher. Okay, but yeah, we can take a configuration of code. For example, here you can see that there are documentation updates. So for example, we have a staged release that hasn't been released yet. But here you can see changes in documentation. You can scroll down and you can see that there are changes in documentation which basically become a part of our product. This documentation is Russian. So for every release, you can access documentation for this particular version, which was also not the case for Miki. So users of plugins, folks with versions can use this documentation. So yeah, basically having documentation as code is a win for everyone. So it's a win for contributors. It's a win for maintainers and it's a win for users. That's why it's important to have this documentation. And many plugins in fact moved to that long long ago. The problem was with our plugin website because it basically looks like that. But yeah, thanks to Miki and thanks to other contributors, we had good progress on that. There is an epic in Jenkins genre about adding integration between our plugin site and GitHub. It's not only about publishing documentation, but other stories. For example, publish and change logs. So yeah, you have seen this change logs. It's a release drafter. It's also a GitHub integration. Plus, there are other stories like taking topics as plugin labels from GitHub, making documentation, making some statistics like stars and contributors numbers from GitHub. So basically making this portal more accessible and providing some additional information to users. And documentation is the first step. This first step has been revealed. There is an announcement in the developer manifest. And here you can see that there are just two examples provided. Basically, when this change was implemented, we had around 20 plugins, which used GitHub, which we referenced in GitHub. As the documentation side, just because plugin developers didn't reference Miki as they were supposed to. This approach didn't work. But right now, if you specify GitHub as a URL. So for example, here if you go to the information support, here we have a plugin model here. And if you just use an expression like that, so URL, you point to GitHub. Then once your plugin is released, Jenkins Update Center will process that, inject red links, and then plugin site will be displayed. So how it looks like. So for example, here's a configuration as code. This is a new documentation which is being published. And it goes straight from GitHub. So with all the images, with all hyperlinks, so related things, et cetera, all of it works. And you just specify URL, and then you will get the presentation published automatically. If you want to see how the previous page to look like. Yeah, it's one of five Jenkins performers, et cetera. But yeah, Miki for this plugin looked like that. Yeah. So basically, like that. And the opposite change look. So anyone who was visiting this page, they just saw this opposite information instead of doing the presentation. So yeah, the change was announced a bit more than one week ago. And over last week, we had more than 30 plugins migrated. So just in one week, we got a pretty good adoption. So there are major plugins, for example, Gradle plugin, Kubernetes plugin. Also, main data strategy, and many other top plugins that they moved to the documentation. So now the documentation has been retrieved from GitHub. And basically, we invite all contributors, all plugin maintainers to start using this flow because it's much more convenient. And really, if you need the one line change in, if you use Mavenflow or Gradleflow, everything is, will be published. And that gets a bit for Miki's plugin. I'll see you in a second. Actually not. Nope, I haven't implemented it yet. I just made a note to say, God, I forgot I got to do that. Yeah, maybe there is even a pull request for that. So yeah, our recent plugins, for example, folder authorization from Google Summer of Code, GitHub branch source, also audit log from our feature, all of them started using GitHub documentation from where they began. So yeah, now all these repositories automatically get a good documentation. Okay, so basically that was my update. There is still a lot of plans to do. So for example, in links, I want to have change lock links here maybe in the publishing of the documentation, because we can render change looks right in the plugin website. Same for issues, etc. So there will be a lot of changes. And there is also other changes in review right now. The project is in front of the site. So it's backhand on this project. So there's a change from was made to support. Because right now we can retrieve from the root. But this change we will be able to retrieve me or the pages from another locations. So we can use it for example, to publish change law can be or to publish additional documentation pages. So on the limitation will be GitHub API rate linked because it's really a problem. So plug inside the API caches all the outputs. So basically it's one request to release, but still, yeah, there are things to be aware of that. But we'll see how this go. So like what is the refresh rate once now that I have now that I have registered the platform label or plug in and I have done that. I've released a version of it and it's in there. So when I know dash. So I've, I've released it. If I updated on GitHub. How, how is that update detected is it only on the next release so the publication only occurs at release, or is there some periodics, periodic polling process that checks for change. Yeah, there is periodic point. There is cash with the spirit expiration. It's about six hours if I recall correctly, I don't need to change check the code. But yeah, so the documentation will be always updated when you're cutting your release because there is cash validation logic. It will be also periodic updated even if you don't do releases. So right now this buggy updates that shows master branch. There is a ticket, which suggests pulling documentation from label. But yeah, it's not implemented yet and some cases it may be advantage and some cases maybe disadvantage. So I'm not sure what they will implement it finally. Okay, great. So, so polled. There's a periodic cash refresh. And, and right now it's pulling from the master branch with provisions potentially in the future to allow me to say that I want to show something. A different file not just read me, and I want to pull from a specific branch. Yes, so that's okay. Any questions. So one thing that I had suggested on the list was, it would be okay if I started submitting for instance, tickets to various, what I'd call interesting plugins proposing newbie friendly tickets to make this transition for plugins it seems like a task that would fit with someone who is not terribly experienced but could submit to individual plugins a pull request to make the transition to the yeah Hacktoberfest was the place I was thinking of it. So my plan is to have a ticket template for that, because I really wanted to create a bunch of tickets for plugins we would like to migrate. So one thing that right now immigration requires minor changes. So there is no plugin installed on conflicts which allows to extract a ski dog or markdown from this page. There are such plugins. So I wanted to chat with Jenkins Infra team before really creating these tickets because if you offer a way to export the skeleton of the page. It would help a lot. Because otherwise, in some sense it will be newbie friendly ticket. But it might be also monkey work. Yeah, usually when I retrieve the documentation. I do a lot of copy edits because of this documentation is mostly obsolete in many cases. But would be better if there was generation of a ski dog markdown from this page so that they can set some time. Well, and along the lines of that automated generation at least for me and the documentation I was generating online help that came for the various fields or things was actually quite useful as a source to put into the documentation. I just copied and pasted it though so it's a good idea to use these documentation sources as the beginning skeleton. Yeah. So it's my plan. Yeah, I'm working on October 1st work and as a part of that they will be definitely a lot of tickets for documentation information. Because this story is important to the community. This story is helpful to users and it's newbie friendly. Thank you very much. Yeah, I love the results we've got so far. I had a question, should we, how did you, how do you get the count of number of plugins that have adopted the technique and should we track it as part of the regular docs to say hey how are we doing put up a graph and part of our metrics or not relevant yet. So, I basically do it, how to do that, if you go to a base Jenkins IO. So this is our center. It reflects this center to repository on Jenkins infrastructure. So it's our internal update center which basically generates information for one school use updates Jenkins as a source of updates, but there are also additional plugins which is exposed specifically for plug inside. For example, that is plug in documentation URLs. So this is a JSON file, which basically includes documentation URLs for every plugin. Later they will be also change lock URL and other fields. So this is how I plan to add support for more fields. So this is how we check how many plugins lose GitHub. Basically like that. Yeah, now that. So this approach has some disadvantages. But yeah, you can easily see that there are 52 plugins which define GitHub as a source of documentation. So these are 52 released plugins. But since I started the project, there were 28 plugins which both released with GitHub documentation, but you can check the list. Not all these plugins actually being published as documentation because in some cases you can see that the documentation points to different GitHub organizations. In such case, we do not publish this documentation right now. We could but it's not implemented and I'm not sure whether we want to implement that. In some cases, yeah, there are just, for example, for Perl plugins. There are also external source in some case, there are custom paths. So for example, yeah, so not quality gates points to read me in the even if it's master, it won't be published right now. So I created a pull request to fix that. And basically is being a patch below the fix that once it's released. There are also pieces where just random stuff is being referenced from GitHub. But yeah, for the most of the plugins, it's more safe for so most of the plugins you can find with this list actually get published. But not all plugins which migrated to the documentation have been released yet. So for example, I mean great for all my plugins. But I haven't released all my plugins yet because I want to release it with some meaningful features to consumers because if I release a plugin this 100,000 institutions and basically everybody has to update the plugin just to pick up new documentation. It doesn't feel right to me. So, yeah, that's the current state. Any questions. No, thank you very much that's that's quite impressive. Thank you, thank you. Okay, so yeah, if somebody wants to contribute basically there are two repositories. We have the code base. So this is playing inside API. And there is also play inside, which is content. If you're a JavaScript developer, you cannot contribute to the content. And there's a lot of changes which we could do there because the content didn't evolve too much since the component was introduced. For plug inside the backend it's basically Java. This jetty as a API server. So you just expose the rest API and then this rest API gets consumed. So yeah, that's pretty easy. In terms of the plug in site itself it's front end JavaScript I assume there that that's probably not newbie friendly, but a JavaScript developer would be a deeply appreciated addition to that that piece of the world. Yeah, and I would actually say that it's newbie friendly because well, I'm not a JavaScript developer at all. I was able to get it running in just few minutes because it basically use young. There is documentation for that. How to get it running how to verify that. So, and yeah, I was able to get running almost immediately in development flow is real time changes for visualization. And the code itself is also pretty fine especially for once who is familiar with JavaScript and react. For example, he is my cool request for a collapsing comply to dependencies by default. So instead of having something like that. You have increased dependencies collapsed. So, without prior knowledge of how we react etc worker, I spent less than one hour to implement it. So I think it's related to newbie friendly. Excellent. Thank you. Thanks very much. So we have any contributions will be welcome. And I'll probably add it to October fest as well we find my goal to generate enough newbie friendly tickets. Okay. So if there is no questions I will stop scratching. Thanks. Thank you. All right, so next topic was community bridge sub projects for docs. And I don't have a dramatic anything dramatic to offer there other than that the crucial. The key part of that is the list of project ideas, and that is being assembled now I assume that two weeks from now when we meet next. I'll have much further to discuss and in developing it from there. Oh, like any insights you need to want to offer there. How is the I assume it's community bridge experiment with Slayton noons is progressing and anything that we need to learn from that. It's the project itself is progressing. Basically it's also related to documentation seek because the objective of the project is to generate instance specific specifications of Jcast YAML files. So basically, it will allow to embed documentation for example in IDs, because the adjacent schema can be used as a source of documentation. So there is a good purpose there. We will likely ship first code beats in the next release. There is a lot of things to be done but the progress is being made. Regarding community bridge itself. I rather put onboarding projects on hold. So yesterday we had advocacy and outreach seek discussion. There are some issues in community bridge right now. For example, it's not clear how we do payments to students because the recommended process doesn't seem to work. And also, yeah, just other minor issues. So right now, I wouldn't like to onboard new community bridge projects right now until we have a job with specification of the process, and until we figure out how to do payments. So, yeah, project IDs would be definitely appreciated. And by the way, the results outreaches happening now and the outreaches also allows to documentation projects. Thank you. Thanks very much. And sorry that I missed yesterday's session with advocacy advocacy and outreach. So if you want to take the next topic, the Hacktoberfest topic. Okay, just a second. So Daniel Beck is that you know my change look for LCS release but not change look amendments for the change look. So you don't want to see typos. Okay. Okay. So yeah, I can share my screen. Oh, so I need to stop sharing. Great. Yes. Let me do that. Okay. It's still useful that somebody has to explicitly stop screen change so that it's not like in handouts on air. You need to separate person just to verify what's exactly going to be to broadcast. Okay. So, this is my screen. We do. Yes. So, yeah, there is another announcement and the developer may at least about her trooper first. So basically, we are preparing to the hard trooper first. It's going to be delayed because yeah, there are many other things to handle. But yeah, her trooper first starts on October 1. So we still have some time. We'll definitely announce something. We have some meetups in progress. But what we really need to prepare right now is a list of projects. So, for example, here you can see a list from 2018. So there is a number of projects for each of them. We had new befriended tickets. We had stuff guidelines and we had maintainers who were able to review changes. So I want to have something like that this year. For example, Jenkins core for website, they will stay there. We definitely need to leave link filters, which have been created already. Jenkins X will stay there. Yeah, we will be cross-planeting a bit like we agreed to scar. So, yeah, there will be also some bus in Jenkins X and yeah, we will be posting each other. The configuration is called we'll be there. Then Jenkins, I will be in Java 11 definitely won't be there, but maybe we could have some additional projects. Yeah, for example, artwork documentation. Yeah, and just documentation. So if there are any ideas what we could improve. We could have migrations will be there, but yeah, we could suggest other bits. For example, we can integrate some of the Miki to Jenkins. We still have a lot of developer documentation which is on the Miki and which could be moved. So, yeah, we could use it as opportunity to do that. So then the page that we have here the 2018 page will do something similar I assume for 2019. Yeah, it will be pretty much the same. The only difference is that I want this page to be complete as soon as possible. The Miki it's a blog post for 2019 and there will be a page likely somewhere and seek or under events. I haven't decided yet. So maybe I'll create some events October first. There will be 2019 on this online formation and then once we get somewhere to October first, the timeline and we will just report to the species and blog post. So that's my plan. Great. Yeah, one thing I want to organize a meetup around first of October. So yeah, I wanted to invite you Mark if you have some of the ability because we have some content about contributed to Jenkins. So we could use this content as a grant opening for October first. So I want to have online meetup as an opening this year. I like I like that very much. I had the notion I think I'm going to try something even a little for me a little more radical I'm going to contact some local universities here that have technical writing programs and ask if I could go talk to their technical writing class locally there and invite technical students who are students at universities here nearby to to join in during October first I think it's a great opportunity for them to do something that they've never done before but they will professionally when they graduate with their degree in technical writing. Yeah, anything goes to open source so everything goes to portfolio. So why not. Excellent. Thank you. Thanks very much. Now, is is October Fest. If I want to see progress track progress and whatnot should I be looking in the advocacy sig is it is it mostly on the mailing list where the where you're doing most of your status reports. I don't understand. Great. Okay. That's my plan. Excellent. Thank you. This one's going to be a lot of fun we we also intend to do a meetup in in the Denver area here will actually I hope to do it on a university campus. And that way I've got a chance to get a whole different group of people involved. You mean for the first minute. Oh, right. I want to do one I want to do it physically and and see if I can encourage more contributors in addition to the online work. We'll create the Google look whatever just to continue this stuff because we have for meetups planned. And definitely, if you want to organize meetup anyway, it will be help. Okay. Any questions. None for me. So, next topic had been related to governance board elections and the documentation officer. So, Markey, maybe we want to have you be the voice for this one as to get us yet another voice are you would you be willing to be the voice describing. Yeah, totally. So, we had the governance board meeting, and we made a, there was a lot of proposals voted on one of those proposals was to add a new document and that officer was for the documentation, which essentially is like the website officer and to be defined as the documentation. So, that was voted on. It was approved unanimously. So that's awesome. And I believe the nominations start in two days I believe it's the 15. Check on that. But whatever. Oh, today. And that goes through November. So, super awesome. Looking forward to it. And just checking for nominations but yes, would be nice. And that's all. Thank you very much. Then we've got just a few minutes left so I've been capturing for good or for bad data trying to see if, if the data might help us on our progress with regard to Jenkins that I owe so the CNCF the cloud native graph stat site. This graph was captured this just today for the last year of time to merge so that the time between opening of a pull request and its merge. And on the left hand side you'll see that the scale is exponential it's yeah nonlinear. That first line one hour, the second 10 hours and for the last four or five weeks, we've kept our median time to merge in the under 10 hour range so we're being responsive. I think I think that was a good sign that that's okay we're, we're handling things we've got plenty of open pull request still, but good progress. Our number of contributors and the contributions in the last month have increased compared to two weeks ago and four weeks ago. The graph shows that and our number of open pull requests is actually down with the number of closed up significantly so we've last time we met we had 15 or more pull requests open we're now down to 10 open doing good job progress processing them. So if these measures are useful or not. It's just hard for me to generate the measures after the fact so I've been capturing them and we can always ignore them. I think it's good data to have. So that covers all the topics that were planned for the meeting anything else that needs to be discussed here today. Nothing for me. I have some time to discuss whether we could facilitate attendance in this meetings because we have apparently more contributors working on documentation that with us during basic meetings. So I wonder what what we could do in order to improve the situation. One of the ways is to just agree that, for example, every month we do a demo and for example, we could run it as online meetup or something like that, maybe every two months. For example, you have some stories. We figured out what to do with Svager Hub. We figured out here we can demo the documentation side, maybe something else from our previous achievements. And it would be a good thing just to have online meetup or maybe developer hardware like we were discussing before. Let's see. Yeah, it's just an option how we could make it how we could improve the outreach. Right. I also think it would be good if we started, you know, some of us like a social media campaign right before meetings or some some way to generate interest online. Yeah. So when you when you say social media market in that case you're thinking things like Twitter. Yeah, Twitter, LinkedIn, you know, we could have the Jenkins account is tweeting, you know, hey, the documents is about to begin. Okay. Good. Okay, I like those. So in terms of hosting an online meetup. Like would that be something like this where we just do it on a with a with with a session through zoom or are you envisioning that we do something through Google dot through Google online meets what how is that working for you. Well, I would prefer to just use zoom. Okay. I don't have strong opinion. Okay. But this and this would I assume be something that would happen outside of the meeting it's intended to promote people persuade them. Hey, you should come here are cool things that are happening in docs. If we if we called it something like docs this month, and regularly had the meeting just to show. Here's the last month's worth of cool things that have happened. Is that sort of what you're envisioning. Yep. So yeah basically we can use the existing platform. So system about creating something else. Yeah, I have some concerns about YouTube channel, because you basically have a single YouTube channel for all meeting recordings and for white events like demos, etc. It's a minor thing. Well, just, yeah, just by doing online meetup, I think it won't hurt, especially if you can show some user facing features. Okay. Last year we changed a lot on the ginkgo site and like insight. I like that. That's a good idea. Let me take the action item to get that scheduled and let's try it. So maybe not committing to every month right now. Maybe we could just try one event. I plan to do the same for jinx developer tools. So this is jinx developer huddle was thinking about. Well basically documentation can be a part of the separate could be a separate thing but maybe if you could run one event and see how it goes. I like that. Great. And you say you were calling it a developer huddle so this could be a docs huddle that kind of thing. Yeah, we can just call it jinx developer huddle and just rotate topics. Right. So without creating additional entities because if you create five different huddles then you have to maintain five different huddles. Right. You have one it's easier to manage. I like that. Good. Okay. Other suggestions of ways to encourage attendance. Let's see events calendar to highlight. Yeah, update the events calendar. You noted Oleg that the meeting the meeting URL is not there and that's a good one with URL. Though that probably won't increase attendance dramatically. Okay. Other suggestions. Thank you. Any other topics that we need to go over that we need to review. Don't have anything specific right now. Yes. So, yeah, that is just a lot of things to be done. Yes, indeed. All right. Thanks everybody. Thanks very much for your contributions. And we will meet again in two weeks. Thank you. Thank you. Have a good weekend everybody. Bye.