 Welcome, this is the Jenkins documentation special interest group. It's Friday, April the 24th. Thanks for being here everyone. I'm going to. Excuse me. I'm going to share my screen and let's look at the agenda. So what I had was. Action item review, Google season of docs. I'm going to share my screen. Status of the solution pages. Documentation roadmap and projects. And if we have time. Data on contributors and contributions. There's no requirement that we, we need to get to that. If that were just to be left in the document, that's fine. Oleg on the status of solution pages. Is that a topic you want to include in the agenda? I'm not hearing you. It is. Yeah. Okay. So it explains. Yes. So I would like to discuss that for sure. Great. Excellent. Okay. Are there any other topics that need to be added to the agenda? Nothing specific from me. I wanted to discuss contributor guidelines, but it might be better to do it next time. Because I still want to finish some items. Okay. All right. And it looks like I have to stop my show. There we go. No, we've got one more addition that we need to add. I had to find the right screen to me if he's joining us also. And Slayton. Good. Okay. All right. Markey, any topics that you needed to add to the agenda? Nothing other than what's already on there. Okay. Great. Excellent. Thank you. Okay. Then let's, let's go ahead with our. So we had a request to put the docs project ideas in a pull request to Jenkins.io. I think that's done now with, between the efforts that Oleg's done ideas that I've put in. We've captured roadmap entries as well. So I'm considering that one done anything. That needs to be kept on that one Oleg that you're aware of things that I may have missed. So I think we could definitely extend to this page, but yeah, I think that we cannot close it. Great. Okay. And I still owe a doc SIG summary. I tend to drop in on the governance meeting and periodically give summaries there, but I, we need a blog post. And so. Yeah, especially since now we have J sort, et cetera. So you may highlight this activities a bit. Right. Exactly. Also, maybe a status of plugin documentation migration. Yes. This is pretty good there. Well, and we've, we've now got, we've just, we're just about to get a new how to guide for, for the participate page or series of guides. Basically more retirement of wiki pages. So there are a lot of, a lot of things to highlight there. That, that'll be my, my item continued. We had one more. Palm and bomb developer meetup. There's been some, we've released palm 4.0 now. Oleg, is this one we should consider for the near term or rather let it wait. I think we should do that. And I'm not sure whether James North and JC are available. If not, I'm ready to do this meetup, maybe together with team. I will think James and Jesse again. Just quite busy with other stuff. Right. Well, but, but you're right. Tim Jacome would also was also deeply involved in it and would probably be a great presenter. For me as a plan C. Well, and I think you, you would do excellent running it or I can run it. So do you want me to draft the draft, the proposed text for the meetup? And with me. Okay. Great. Then we had one more list, the GitHub apps and plugins that use them. I don't recall the context here. Could you give us some context Oleg? Yeah. So it was discussed one or two months ago that we have a number of GitHub apps which help with documentation. For example, release drafter, another beats, but for plugin developers, it's not clear which apps we offer. And there is separate problem that we don't have a documented process of how we review apps. This is something which was brought up in the developer mailing list this week or last week. So, yeah, probably, so the list of approved apps, we definitely need to put it somewhere, maybe on infrastructure, maybe on just.github repository. And we also need a documentation like the JEP, which would document the process of approval. No current process of approval. It's quite easy. It's approved. Okay. So that because certainly we've documented and even done webinars on release drafter and on dependabot, but this is about what if someone wants to add a new one? Yes. Okay. Got it. So I guess it becomes less relevant to these days because many apps move to the GitHub actions space and for GitHub actions, you don't need special permission to enable something. But there are still a lot of things which are available through apps on there. So yeah, writing a short JEP wouldn't hurt. Okay. Anything else on action items before we go to the next topic? Okay. Great. Let's take on Google season of docs then. Oleg, do you want to take the take the voice there? Okay. Yeah. So Google season of docs is something we've been discussing for a couple of years. Since it was hinted at the G-Soc mentor summit. Last year we applied to Google season of docs, but we haven't been accepted if you scroll down because there are references to our application and retrospective we had after we were rejected. But this year initially we wanted to apply again and when we started the discussion one month ago or so, we had some struggles to find Orc admin and mentor team because if you want to run this program, you still need people to manage. And while it comes to Cosmo because you'll still have administrative overhead, et cetera. Personally, I believe that this overhead is well justified. If we could get a part-time professional technical writer or just somebody, a professional, it would be a great addition to the project and it would help us a lot to push the documentation. So at the governance meeting on Wednesday, we had a discussion. Basically it was a go-no-go decision. And since we had many contributors who stepped up thanks to Sladyn, thanks to Marky, Christian. We agreed that and to Mark of course. So we agreed that we will do a best effort attempt. So I spent a couple of hours on Thursday. I wrote this landing page. I also created an application draft which is currently ready for review. Any feedback will be appreciated because basically this is what we need. You'll also need mentors to register on the JSOC website. I'll send it later. But I think that from the application side, we are all set. And we will benefit from having more ideas. Excellent. And the timeline is relatively short on this. The applications must be submitted by May 4th. The applications must be submitted by May 4th. But actually I have already submitted that. So how it works. It's not like a JSOC application website. Instead of that, you just submit a Google form. And you can edit this Google form until the application deadline. So similar to how it was last year. I submitted the form. I also put a field here in this application document. Later I plan to move it to Jenkins.io website. Similar to what we do with JSOC. It contains text, et cetera. Thank you. Thank you. Thanks for comments. I will reply there. I'm also actively going through and changing some things. So I'm not commenting on what I'm changing. I'm more making things more in a professional document. So if you look at the history of the dog, you'll see the things that I've changed. And if you have any questions about that or concerns, I'll definitely raise them that way. But I'm not commenting on body changes. Most of them are just grammar and. That's perfectly fine. Anyway, I consider it as a boilerplate. So before the final application, I submit, I will submit the final version to the Jenkins website as a pull request. And there we can do a trace review here, whatever you change just to do it. Okay. So you're one thing that the entire application form is plain text. So it's not marked down like JSOC. Well, it's not a big deal, but whatever. Also, who will season of dogs should it be included in the sub projects drop down on Jenkins.io? Or is it fine? I have some concerns about sub projects drop down to be honest. So when we started it, there were no special special interest groups. So it wasn't reduced before. And right now we, the fact that have sub projects by special interest groups, for example, we have, if you go to JSOC, sorry, to the documentation seat that we also have projects listing. Okay. And yeah, I understand the importance of highlighting some top level projects there. But yeah, I wouldn't put any sub project to this page. And maybe I would consider removing things entirely because the solution is so nice. Evergreen is even deep free, say I would say. JSOC is running infrastructure. Infrastructure could be just converted to a SIG. CICD and remit apps are a part of advocacy. Contribution is called is potentially a part of platform or currently a part of the planning to find remote. It's a good question. But yeah, we deal with it. So I don't see a much future for sub projects top here, unless it helps us to facilitate contributions to this area. And right now it doesn't. Well, or if sub projects should actually be renamed special interest groups and get this list instead, right? Because we have sub projects is, is a dated, a dated menu now and sort of outdated menu. Good. Yeah. So we, we can just squash them and we could use community top for something else like put Jenkins online meetup here. You could remove a week. I have no idea what account management is doing here, but yeah. So it's a subject for the work later. Right. Yeah. Okay. Yep. Sounds good. Good questions. Thank you. Anything else on Google season of docs or any questions for Oleg on Google, Google season of docs. I think I'm good. Now, I'll go ahead. No, no, I was just saying for me, the landing page also yesterday, I mean, I had some suggestions, but yeah, it looks good to go as is. Yeah. So with just, I'll go ahead. Yeah. If you have any suggestions, just admit the request. So just to explain why I merged it without fully closing suggestions. Firstly, because you are proofed it. Secondly, because I wanted to have something in place so that we could facilitate contributions by others. Yeah. Perfect. Perfect. Wholehearted agreement on that. That was, that's. Okay. So it doesn't mean that this means feedback. You just admit a pull request and we can review it incrementally. Okay. So anything else. Yeah. We need more project ideas. Well, theoretically. And we need more potential mentors. So if anyone is interested to participate or if someone has an idea of what specifically we could change, that would be great. Because currently we have three pretty broad project ideas. Just submit proposals. Thank you. All right. So we take on solution pages. This is a, this is a fun one. I'm going to show something that is really a thing of beauty. Actually, I love what you've been a connection. He did with this page. Go ahead. Me. Okay. So firstly, thanks to the being for the work on this page. Just to provide some history solution pages have been introduced as a part of Jenkins to do zero website. So when we create Jenkins Iowa. And as a replacement for the previous website. Historically, they didn't have a listing of use cases at all. I edited maybe three or four months ago. It's just because I wanted to remove solution pages from the menu. And right now in sort of solution pages, we, we still have that. But yeah, I wanted to remove it. So why I wanted to remove it is because the layout is currently really cool. Thanks to spinac. But if you start navigating to content, you may see that all these pages basically dated. And someone. Yes, someone just terribly dated. Formatting is pretty bad, et cetera. And I would argue that the most of these pages need a completely right. And it's especially terrible that we have so bad. So we have so bad pages. We have a lot of content. There is a lot of articles, for example, about using Jenkins with Docker using Jenkins with GitHub, et cetera. But we haven't been maintaining these pages. Yeah, so some pages look slightly better. I'm just having no content. Obviously we are missing some key use cases. For example, Jenkins with Kubernetes. There is no solution page for that Jenkins on GitLab. There is no solution page for that. And so on and so on. We have expertise. We could create them. Or we could just put links to existing content. So that could be a lot of composition of work done to just completely rewrite these pages. I was thinking that it could be a good project for Google's season of dogs. Or maybe a good set of new, different issues for Jenkins website. My proposal would be to consider adding it to roadmap as a future item and creating other framework around that. At least in the work of that on the C page and creating issues for that. Yeah, as an example, we have three pages here which have tutorials already in our documentation, but no link from the use case to the tutorial. And so there are lots of things we can do to improve these themes. We have stories from users that are arriving now on other locations. And they are stories typically about one of these use cases that could be linked in here. So lots of opportunities to improve. Yes, immediately I would rather remove it from the menu. Because our current situation is that we have almost no links to documentation. So if you click on the documentation menu, there is just a link to use Jenkins. You open that and basically you stack another page which doesn't really provide your navigation. So I would rather kill use cases or just keep it as a single link. Instead of that, expand use Jenkins to something like user guide, documentation guide, administration guide. Maybe installing Jenkins and I think it would be more helpful for those who seek documentation. Right now, to be honest, I look for Jenkins documentation in Google. Right. Yeah, agreed. At the moment, this page that I'm showing is not even accessible from the menu menus. If I click, if I go to the blog, for instance, and then I click documentation use cases, it doesn't navigate. So we've got a page that is a beautiful thing that we're not actually showing that we don't have anywhere in the navigation. So yes, abundant things to improve. Okay, I'll probably just follow your pull request for solution pages. So if somebody is interested to take action items, maybe to just create issues or to write something. So for example, Mark is a maintainer of github plugin and some Kubernetes plugins. So it could be one of the options to at least create a skeleton. Also, one, one potential opportunity. Right now, we have a hard-coded list of plugins on this page. Maybe we could just drop into it entirely and instead of that, provide a label query to the plugin website, because we added support for queries and manually maintaining a list of plugins on solution pages for me, it looks like a waste of time. I'm not sure I'm understanding that you say a list of plugins. For example, please click on Java. Java. Okay. Okay, so we have six plugins listed for Java. Actually, the list is quite high and it's pretty much for everything else. There would be two ways. First way is to just provide a high percentage of the plugin site to a label search. Another option would be to provide the iframe or whatever. So we, again, provide information generated by the static plugin site on this page. But maintaining the list of plugins in just another case for me is just a waste of time and it will be always obsolete. And so this list is actually maintained inside the page that describes this. Okay, yeah. It's not maintained inside. Right, right. It is orphaned inside. Very good. Yeah. Your use of precise verbs is a good help here. It is orphaned and inside that file as a list. Okay, so just kill this information replaced by our plugin site link for now. And then the future have an automated generation of such information because we could use it on other pages as well. But definitely not as a minor maintained content. Yeah, so the idea is to just apply it by the what's by the plugin site. Yeah, that's yeah. Actually, we could do it at the built time, because for example, if this list is rebuilt every time we built the Jenkins IEA website, it should be acceptable because we built Jenkins IEA quite often thanks to continuous delivery. So maybe the first solution would be to just query update center and generate the list. So we all really query update center when we built the Jenkins website, which causes a lot of problems when updating site is down, but at least we could use of the same approach here. Right, it would, it does not make it any worse that we are dependent on the update center and in fact our users are dependent on update center so that seems very reasonable. Maybe, but yep. So, if somebody is interested to spend some time we could definitely improve these pages just like such things. Now on the on the solutions page like that when I as I was looking at it, I saw what I might call themes here that there are SCM systems, Bitbucket GitHub and you noted GitLab and for me giddy. There are languages like C and C++, Python, Java, PHP, and then there were platforms like Android and Docker. Do we need a thematic orientation here or is is I mean the flip side is people coming here see this and probably immediately see the thing they want or they don't and it's there's no need for further categorization. It depends on how many solution pages we have because right now it's not a problem. But we have just 11 solution pages. If we had let's say 100 to 100, which represents the skill of the Jenkins project and supported and definitely you would benefit from some. So, I would prefer to solve this problem once we get there. And once we get into this problem I will be extremely happy. But then my solution would be to just add additional field for categorization and maybe write some JavaScript which would allow filtering them. It's still great to have this grid of technologies which are just sorted by alphabet, but then if we provide some support for filtering them, it would be awesome. Great. Thank you. And my JavaScript skills enough to do that. So I believe that it's not ideal. I do like the idea of getting the Kubernetes piece in there and linking. I think that would be a huge hit. Yeah, you have this in the Jspot project idea. And yeah, I wanted to create this page anyway. But so somebody wants to contribute. Let's just do that. Excellent. Thank you. Anything else on solution pages. My action item is to create pull request to make the surface a bit more official. Assuming that we agree that it's something we want to do. All right. Next topic then roadmap or anything else on solution pages before we go on to roadmap. Okay, so here is a thing of beauty. Thanks deeply to Oleg for this this effort. Here is the documentation segment. It's only a piece of the total documentation contribution to the Jenkins project but here's a view of the documentation roadmap from left to right it is current near term. Let's see headings are released current near term and future. And so static plugin site continues to get improvements but is fully deployed and ready to go. We are about 350 plugins now migrated their documentation to GitHub. So that's in good progress. And we've we've got some progress on the documentation migration to Jenkins.io and project ideas to further that. Then in the future Jenkins on Kubernetes admit extract the administrator guide from the Jenkins handbook, improve the user guide portions of it and solution pages. Yeah, these they were put there when I did the when I did the PR to put the solution pages on the on the docs page. Okay, thank you. And then it's still yet to be done for G sort, but it's great that it's already in the roadmap. Yeah, for me I felt like this is this the work that you've been I could done is such a catalyst for us that what it what this is talking about is the story about how do we, how do we improve that even further. And so we've got a we've got a Jira ticket to represent it as an epic. So one question. Do you want to use Jira, or maybe should we use GitHub issues and get up. Oh, that's a very good idea because GitHub issues are enabled on Jenkins.io we could use. We could keep it entirely centered on the Jenkins.io repository. Yeah. It's much easier to manage on GitHub because it's like almost everything for Jenkins.io already happens via GitHub much easily so it's and plus we have the copy editor scheme and all of the full request mechanism that make much sense to have all the issues also there. Right, good point. So what if we put an action on mark propose. Let's see propose the shift of docs projects slash epics to GitHub issues is right now there are a number of them that are on GitHub or on Jira, but let's use GitHub issues. Yeah, so and the docs feedback form actually has already switched to GitHub issues. Oh, like, or at least maybe maybe I should say it differently. There is a feedback form. But there is also improve this page which takes me right there. And then there is report a problem, which opens up a GitHub issues page. What we don't have is the, let's see, the one that was feedback on this page and it's not visible on this on this particular page, but that one adds an entry to a Google form I think that's what you're alluding to right oh like here on the docs feedback form topic. Oh, you just muted. Okay, sorry. Okay, so all the documentation allows us provide a feedback form, but this feedback form goes to whatever Google feedback form. To be honest, I still have no idea what is the link and whether I can access that. Okay, then I just want, but yeah maybe we could just switch to GitHub issues. The only problem with that is that it requires a GitHub account to report an issue. On the other hand, the Google forms, for example, is not accessible from China. So I'm not sure what exactly would be better. Maybe we should keep both ways. But I think that we should recommend GitHub issues by default. I like that idea. It gives us a tracking workflow today what we have to do is I end up every week or so opening up the docs feedback details sheet like this. And I'll just embed this link because it's a publicly readable sheet, and I checked the latest feedback. And that latest feedback is usually, I have to think very hard about it before it becomes actionable. So, so let's I'm going to link to the feedback form here. Well, maybe we could do some automation so that even these forms somehow ends up on GitHub issues. Yeah, I think that it would be easier to just provide users a way to report something right actually get quite a lot of feedback. Oh, yeah, this is this is multiple years worth of feedback that's collected here. And yeah, just look at the date and all the data is quite recent. Oh, yes, and we, I regularly that's why I regularly look so for instance, you'll see this one right here that is the wrong public key. This was absolutely related to current change to recent changes on our packaging. Right. So this is somebody reporting hey, the public key instructions for installation on red hat didn't work or on fedora, and they were correct. And it was a reminder to me, keep searching that so this has been helpful. It's also, oh, go ahead. Yeah, sorry. I think that in principle it would be much more convenient to put on GitHub issues because firstly it becomes publicly visible. Then we can just put a new befriending label in some cases so that somebody fixes that eventually. Then we can also add to a picks we can just suggest the feedback provider to submit a pull request, which is relevant sometimes. So, from a facilitating distribution standpoint, get happiness is much, much better from reports of user experience. It's up to discussion. But again, get happiness provides a two way communication channel by Google form is basically just submit feedback and forward. Exactly. Now one of the challenges with that we still need to solve in the in the connecting to GitHub issues. Currently the GitHub issues connection, or the improve this page link is this is not connected to the specific contribution location for things like pipeline syntax, where they are being assembled from multiple places. And for that, we will need to top the logic a bit. I was thinking about the same for roadmap and for other items, because for roadmap, it's exactly the same. You can actually improve this page, but you get to lose your humble, which basically doesn't include anything specific to roadmap. And the most of contributions are likely to come to the roadmap content. Yeah, it's a kid is for Mustang, you know, to generate a page like what's the GSOP project ideas listing again, improve this page doesn't help much there. Well, and the, let's see the one that I was thinking of was the weekly change log. Yes, the change right to make a correction to change log improve this page won't help. Yeah. I was thinking about adding some metadata, which would alter the behavior of improve this page macro, and maybe report this problem macro as well, so that they point to the right location on feedback is submitted. Yeah, but there is a difference between thinking about something and submitting a GitHub issue for that. So it's on me, but yeah, I think that in principle it's something we should support. Obviously, for pipeline steps and in the future for system properties will need a bad engine to make it useful for pipeline is actually even more challenging because documentation effectively comes from Java doc. Right. And from health pages. So you would need to link it somewhere to another repository. I have no idea how to do it like that. It's, as you said, there's, at minimum some metadata has to be provided somewhere some additional information has to be provided to, to connect those. Great. Yes, or maybe improve this patient side case should be reference to whatever contributing guide. It's better than just opening the wrong page. Let me take, I think you highlighted one that I should hang my head in shame on that there should have been a GitHub issue reporting the improve this page because that would at least let us know, oh, improve this page needs to be improved. But that is the problem for that. Oh, is there already. Yes, or the issue. So, if you open any page, there are two buttons. One button is improve this page, which is basically opens GitHub editor. Another one is report the problem which opens the GitHub issue. So I have an action item to connect this button to an issue template. So it provides a bit better look and feel. But in principle, one button opens editor. Another button creates GitHub issue and it was created by team Jackam before that there was page history, which is less relevant. So, so, yeah, I believe that we already have buttons in place. Yeah, what I was trying to say is that while we have the buttons and while we have the links ready there. What we don't have is that if I navigate to pipeline syntax and click report report a problem or improve this page. It will end up creating that in the wrong context or on it on the roadmap if I if I go to roadmap and collect report a problem. But will it get certainly, as you said, if I go here and improve this page it will take me to a Hamel file, right, which is not going to is not the thing I probably wanted to edit when I was trying to improve the roadmap. Yeah, so, but it's something which can be fixed quickly. So I was thinking about that. And it's not the first year, which, when I hit this problem, but I have never done it. Got it. Okay. So if you have some bandwidth to create these issues, it's fine. It's just one I had, I had noticed and not submitted and I thought I should submit issues when I notice them. Yeah. But we are a little ahead of it. I think that in general be an agreement that get happy she's something useful for the plug-in site, sort of for Jake say oh. Yeah, agreed wholeheartedly. Great. Now we are nearing the end of our time are there other topics that need to be addressed in this meeting I'll just leave the data in the in without doing a review during this meeting. Okay. I think we're at a point where we can call it an end to the session. Thanks very much everyone for for joining. Looking forward to our progress on Google season of docs and more. Yeah. Thank you everybody have a good weekend. Cheers.