Jenkins Documentation Office Hours, 24 Apr 2020

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Docs SIG 2020 04 24

Description

Jenkins documentation special interest group April 24, 2020. Topics included Google Season of Docs, Solution pages, Documentation feedback form and GitHub issues, and latest contribution results.

GSoD - https://www.jenkins.io/sigs/docs/#google-season-of-docs
Solution pages - https://www.jenkins.io/solutions/
Feedback form - https://bit.ly/2yEAcED
GitHub issues - https://github.com/jenkins-infra/jenkins.io/issues

A

Welcome this is the Jenkins documentation special interest group. It's Friday April the 24th. Thanks for being here, everyone I'm going to choose. Excuse me I'm, going to share my screen and let's look at the agenda.

A

So what I was action? Item review, google season of docks 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, oh, like on the status of solution pages. Is that a topic you want to include in the agenda.

A

I'm not hearing you're like okay. What.

B

Is it but now it is yeah okay, so it explains something yeah. So I would like to discuss that for sure great.

A

Excellent: okay: are there any other topics that need to be added to the agenda.

B

Nothing specific for me: I wanted to discuss contributor guidelines, but it might be better to do it to next time, because I still want to finish some.

A

Items all right and it looks like I- have to start 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 make these joining us also and Sladen good. Okay, all right.

A

Marque and fix that you needed add to the agenda nothing. Everyone was already on there. Okay, great.

A

Excellent, thank you. Okay. Then. Let's, let's go ahead with our previous action item, so we had a request to put the docs project ideas and a pull request to Jenkins at I/o. 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 or that I may have missed.

B

So I think we could definitely extend to this page, but yeah I think that we can enclose it great okay, mm-hmm and.

A

I still owe a doc sig summary I tend to drop in on a governance meeting and periodically give summaries there, but I. We need a blog post and yes, so.

B

Especially since now we have G sort etc, so my highlight that its activities a bit right exactly.

B

Also, maybe a status of plug-in documentation, migration. Yes, this is pretty good there well.

A

And we've we've now got we've just we're just about to get a new how-to guide for this, 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 to highlight there that that'll be my and I. My item continued mm-hmm.

A

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 and.

B

I think we should do that and I'm not sure whether James now and Jesse available with not I'm, not ready to do this meter up my beetle and together. We sting, though I will concur James and Jess again, I just quite easy. Without a stop.

A

Right well, but you're, right, Tim, Jack home, would also was also deeply involved in it and would probably be a great presenter.

B

Yeah, oh me, as a plumb see mm-hmm.

A

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 amita enemies me: okay,.

A

A

Then we had one more list: the github, apps and plugins- that use them. I, don't recall the the context you did you give us some context or like yeah.

B

So it was discussed one or two months ago that we have a number of github which help with documentation example, linear after another needs, but for plug-in developers. It's unclear which apps we offer, and there is separate problem in that we don't have a documented process of how we review ups. This is something which was brought up and the developer mailing list this week or last week, so yeah, probably so, the list of pop rooftops.

B

We definitely need to put it somewhere, maybe on infrastructure, maybe on just don't you have repository and we also need documentation like Jeb, which would determine the process of approval. The current Casas approval is quite easy from our proofs. It's approved.

A

Okay, so so that, because certainly we've we've documented and even done webinars on release, draft or on depend on dependable, but this is about what, if someone wants to add a new one? I, yes,.

B

Okay, got it so I I guess it becomes less relevant to these days, because many apps github actions space and forget hop actions. You don't need special permission to enabled something, but there are still a lot of things which I were able to throw up some so yeah writing a short chip wouldn't kill.

A

Okay, anything else on action items before we go to the next topic.

B

A

Let's take on google season of docs, then oh, like you want to take the take your voice there. Okay.

B

mmm So google season of dogs is something we've been discussing for couple of years, since it was hinted the G segment to summit.

B

Last year we applied to Google, seeing as enough dogs, but we haven't been accepted. If you scroll down, 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 this discussion 1 months ago, or so, we had some struggles to find orchid mean and networking, because if you won't run this program, we still need people to manage, it doesn't well. It comes at a cost because you have administrative overhead, etc. Listen I believe that this overhead is well justified.

B

If we put with a part-time, professional, technical writer or just somebody professional, it would be a great addition to the project and it would as well to push the documentation so the governance meeting on Wednesday we had a discussion, basically was a go/no-go decision, and since we had many contributors who stepped up thanks to Australian thanks to mark a Christian, we agreed that and Mark of course.

B

So we agreed that we will do a best-effort patent, so I spent a couple of hours on Thursday wrote this landing page I also created an application draft which is currently ready for review yep. Any feedback will be appreciated because yeah, basically this what we need. We also need mentors to register on the geosoft website or sent a link later, but I think that from the application side we are also- and we to benefit from having more ideas.

A

Excellent so, and the timeline is relatively short on this- the applications must be submitted by May 4th yeah.

B

We've done some ones and they submitted by my fourth, but actually I have already submitted bit so how it works. It's not like a JSOC application website. Instead of that, you just submit a Google Form, though you can edit this a Google Form I until the application deadline, so.

C

B

To how it was last year, I submitted that form, I also put a field say he and this application document, which I plan to move it to jinkies our website, similar to what we do with JSOC, what it contains text, etc and yeah Markie. Thanks for comments, I will reply there because listed.

C

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 it, all you'll see the things that I've changed. If you have any questions about that, or concerns definitely raised in that way, but I'm not commenting on body changes, most of them are just grammar and that's.

B

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 trivia here. Whatever you change just to do it.

B

Ok, so one thing that the entire application for most plain text, so it's not marked down like JSOC.

B

Well, it's not a big deal, but also.

D

Dog should be integrating the sub projects drop down on jeggings or IO, or is it fine and in there exactly.

B

Thank you. Some concerns about sub projects drawn. To be honest. So when we start today, there were no special special interest groups, so it was introduced before and right now we defer to have sub projects in hand by special interest groups, for example. Okay, we have, if you go to J, so sorry the documentation see they. We also have projects listing.

B

Yeah I understand the importance of highlighting some top-level projects there, but yeah wouldn't put any sub project to this bridge and maybe I would consider removing in the entire, because the ocean is so nice evergreens, even deep freezer, I would say yeah the sock is running. Infrastructure infrastructure can could be just converted to AIESEC a CD, a limited partner for the vocal Shea graciousness code is potentially a part of platform, okay, part of cognitive and remote, and it's a good question. What is but we deal with it.

B

So I don't see how much future for sub projects top here unless it helps us to facilitate contributions to this area right now, it doesn't well.

A

Or or if sub-project should actually be renamed special interest groups and get this list instead right because yeah we have sub projects is, is a dated dated menu now and sort of outdated menu? Good? Yes, so.

B

You can just squash them and we could use community top for something else like put Jenks online it up here we could remove media I have no idea what account management has done here, but yeah. So it's a subject for the work later right: yeah, okay, yep.

A

Sounds good questions late and thank you.

A

Anything else on google season of dogs or any questions for Oleg on Google season of dogs.

D

A

Oh go ahead, say no.

D

For yesterday, I mean I but yeah you.

B

Know so with just go ahead, if you have any suggestions, just submit a request, so just let's know why I merged it without fully closing suggestions. Firstly, because you are prompted. Secondly, because I wanted to have something in place so that we could facilitate contributions by others.

B

Yeah perfectly.

A

Wholehearted agreement on that. That was that.

B

So it doesn't mean that I dismiss feedback. You just said me to pull requests and we can review it incrementally.

D

B

So anything else yeah. We need more project ideas well, theoretically, and we need remote potential Mentors. So if anyone is interested to participate or if someone has an idea, what specifically we could change because currently we have three pretty broad project ideas just submit proposals.

A

B

A

Shall 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 benek connection! He did with this page go ahead or, like me,.

B

Okay, so yeah first thanks to being to the forward in this page just to provide some history solution pages have been introduced as a part of fudging against 2.0 website. So when we created Jenkins Iowa as a replacement for bacterias for tried, historically, they didn't have at least and copy use cases at all, I edited three or four months ago. Just because I wanted to remove solution pages from the mania and right now, instead of solution pages, we how we still have a date, but yeah I wanted to remove it.

B

So why I wanted to remove. It is because the layout has current a really cool thanks to spinning.

B

But if you starting to get into content, you may see that all these pages basically dated and somewhat yes, someone just terribly detailed formatting- is pretty bad, etc, and I would argue that the most of these pages in a complete rewrite- and it is 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, which doc using Jenkins with github etc.

B

But we haven't been making these pages yeah some pages look slightly better and just have no content. Obviously we are missing some key use cases, for example Jenkins with kubernetes, but is no solution page for that Jenkins. On good luck, there is no solution, page for that and so on, and so we have expertise. We could play them.

B

We could just output links to existing content, so that could be a lot of computation of work done to just completely rewrite the pages. I was thinking that it was, could be a good project for Google Docs or might be a good set of new beer and delicious for Jenkins website.

B

Yeah, my proposal would be to consider ending fit to roadmap as a future item and treating other framework around that like distant the work of that on basic page and creating issues for that yeah.

A

As an example, the we have three 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 this. These themes, we have stories from users that are arriving now on other other locations, and they are stories typically about one of these use cases that could be linked in here, so so lots of opportunities to improve.

B

And yes, a immediate item: I would rather remove it from the mania because our current situation a bit, we have almost no links to the communication. So if you click on the documentation mania, there is just need to use Jenkins. You opened it and basically you stuck in another page which doesn't really provide you navigation, so I would rather kill use cases or just keep it as a symbol link.

B

Instead of that takes fund use Jenkins to something like user guide, the documentation administration guide may be installing Jenkins and I think it would be more helpful for those who see documentation right now, I to be honest, I look for Jenkins documentation in Google right.

A

Yeah they agreed in at the moment this this page that I'm showing is not even accessible from the manage menus if I click, if I go to the blog, for instance, and then I click documentation, use cases, it doesn't navigate. So 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.

A

But yes abundant things to improve. Thank.

B

You I would probably just file a report and 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 making a review a plugin and some kubernetes plugins, so it it would be one of the options that least create a skeleton.

B

Also one one potential opportunity: right now: we have hard-coded list of plugins on this page. Maybe we could to just drop in click entirely and settle that provide a label query to the plug-in website, because we added support for queries and manually winking and a list of plugins on solution pages from nooks like a waste of time, so I'm not sure I'm. Understanding that you.

A

Say a list of plugins, for example, please click on Java Java.

B

Ok, ok, so we have 6 plugins listed for Java yeah. Actually this is quite higher and it's pretty much for everything else. So for me, there would be two ways. First way is to just provide a hyperlink to the plug-in side to a label search. Another option would be to provide iframe or whatever. So we again, the private information generated by the static plug-in sent on this page, but maintaining that the list of means just another kiss. For me, it's just a waste of time and it will be always obsolete and so.

A

This list is actually maintained inside the page that describes this okay. Yes, it's.

B

Not maintained inside right.

A

Right, it's! It is orphaned inside very good yeah. Your your use of precise verbs is a good help here. It is orphaned and inside the that file as a list exactly so.

B

Just kill this information, it is by a plug-in setting for now and then the future have it automatically duration of such information, because we could use it on other pages as well, but definitely not as a man and they're maintained content.

A

Yeah so so the idea is to be.

B

Supplied by the what's by the plug-in side,.

A

Yeah that yeah actually.

B

We could do it the build time because, for example, you have this list is that we built every time we build the machine can say your website. It should be acceptable because we built a Jenkins I/o, quite often thanks to continuous delivery.

B

So maybe the first solution would be to just query, update Center and generate the least, so we already quit update center when I rebuilt the jenkins website, which caused us a lot of problems for not dating site is down, but at least we could use of a sim at first year right.

A

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 centers. So that seems very reasonable.

A

Okay, good, maybe.

B

But yep, so if somebody is interested to spend some time, you could definitely improve for these pages. Just like such things,.

A

Now, on the on the solutions page or like there, when I as I was looking at it, I saw what I might call themes here, that there are SCM systems, but I could github and you know, did get lab 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?

A

See this and probably immediately see the thing they want or they don't and it's there's no for the categorization.

B

It depends on how many solutions pages you have because right now, it's not a problem, but we have just allowing solution pages if we get, let's say 100 200, which represents the scale of the Jenkins project and supported that. Definitely we would benefit from some quick addition.

B

I would prefer to solve this problem once we get there and once we get into this problem, I will be extremely happy, but and then my solution would be to just add additional focus, equalization and maybe write some JavaScript, which would allow filtering them, because it's still great to have this grid of technologies which had just started by alphabet. But then, if you provide some support for filtering them, it would be awesome. Great. Thank you and my JavaScript skills say enough to do that. So I believe that it's not a big deal.

C

Do you like the idea getting the kubernetes piece in there and linking I think that would be a huge it.

B

Yeah you have this in the G spot project idea and I wanted to create this page annually, but so, if somebody wants to contribute, let's just do that.

A

Excellent. Thank you anything else. On solution pages.

B

My action item is to create pull requests to make the surface a bit more official, assuming that we agree that it's something we want to do.

C

A

All right next topic, then roadmap or anything else on solution pages before we go on to roadmap I. Think for me, 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, plug-in site continues to get improvements, but is fully deployed and ready to go.

A

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 at I/o 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. Oh so there's something just a little easier.

B

A

These they were put there when I did the when I did the the pr2 put the solution pages on the on the docs page, okay,.

B

Thank you and there's.

C

B

Still yet to be done, 4G, so it's good yeah.

A

For me, I felt like this is this: the work that gbendeck had 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 got a JIRA ticket to represent it as an epic.

B

One question: do you want to use JIRA, or maybe it should be using issues and.

A

Oh, that's a very good idea because github issues are enabled on Jenkins dot. Io we could use. We could keep it entirely. Centered on the Jenkins at I/o repository yeah.

D

Much easier to manage on your topic doesn't have almost everything for drinking, but I would already happens by every government and plus we have the copy editor scheme and also make once things don't have all of the issues. Also, there right.

A

Good point: so what if we put an action on mark proposed mark, let's see proposed the shift of Doc's 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.

A

Yeah so and the the docs feedback form actually has already switched to github issues Oleg or at least, maybe maybe I should say it differently. There is a feedback form, but there's also improve this page, which takes me right there and then there is report, a problem which opens up a github issues page.

A

What we don't have is the let's see that 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. Oleg here on the the docs feedback forum topic.

D

Oh you just mutiny, I'm, okay,.

B

Okay, sorry, okay, so all the documentation tells 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 I believe the server care? Okay, then I just want but yeah. Maybe we could just switch to github wishes, so the only problem with it but yeah it requires a github account to the port Anisha.

B

On the other hand, the Google forums, 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 wishes by default. I.

A

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 darks 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 gonna link to the feedback form here.

B

Well, maybe we could do some automation so that, even though this forum somehow ends up on github issues, but yeah I think that it would be easier to just provide users way to report something right actually good. Quite a lot of, but.

A

This is, this is multiple years worth of feedback. That's collected here and yeah.

B

A

B

At the date and all the data is quite recent- oh yes,.

A

And- 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 chain 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.

A

It's also oh, go ahead. Yeah.

B

Didn't mean to interrupt yeah I think that in principle would be much convenient if with only tough issues, because, firstly, it becomes publicly visible, then we can just put a newbie friendly variable in some cases, so that somebody fixes so that eventually, then we can say affixed, we can just just hit that provider to submit a pull request, which is sometimes.

B

From a facility in distribution standpoint, github wishes is much much better from a deportation user experience. It's up to discussion but again get officious, provides a two-way communication channel. Why Google forum is basically just submit feedback and forbid exactly.

A

And 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 yeah. So.

B

For that we were learning it totally the logic a bit I was thinking about the same photoed map and for other items because for road map, it's exactly the same. You can actually improve this page, but you get looser. Hamo basically doesn't include anything specific. The road map and the most of contributions are likely to come more to the roadmap content and it was for Mustang auto-generated page like what's the G sub project ideas, please think again improve this page. It doesn't help much there.

A

Ellen and the let's see the one that I was thinking of was the weekly change log. Yes,.

B

The changed write it.

A

So, to make a correction to change log improve this page, won't help yeah yeah.

B

So I was thinking about hitting some metadata, which would I thought the behavior of improve this page mantra and maybe a report. This problem, macros, were also that they point to the right location. One feedback is submitted yeah, but there is a difference between thinking about something and submitting for indie publisher. Oh that so it's on me, but yeah I think within principle.

B

It's something we should support, obviously, for pipeline steps and in the future for system properties, we will need a better engine to make it useful for pipeline is actually even more challenging because documentation effectively comes from Javadoc right from how pages. So you would need to link it somewhere to another repository I have no idea how to do it right. There.

A

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 yeah.

B

So maybe improve this patient size kiss should be reference to whatever contributing guide, rather than just opening front page.

A

Although 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 the problem for that o is there already is.

B

So if you open any page, there are two, but us one button is improved. This page, which is basically opens github editor. Another one is a reporter problem, which opens a github wishing so I have an action item to connect this button to initiate template. So it covers a better Lucan film, but in principle one button opens editor. Another button creates github wishy and it was created by Team Jacob before that there was page history which is less relevant, so yeah I believe that we already have four buttons in place.

B

The problems with a behavior yeah.

A

What I was trying to say is that, while we have the buttons as well, we have the links ready there. What we don't have is that, if I navigate this 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, will it will it get? Certainly, as you said, if I go here and improve this page, it will take me to a Hamel file.

A

Right is not going to is not the thing I probably wanted to edit when I was trying to improve the roadmap. Mm-Hmm.

C

B

So, but it's something which can be fixed quickly, experienced developer but yeah. So I was thinking about that and it's not the first year which, when I hit this problem, but I have never the first attended, got it. Okay,.

B

Okay, so if you have some bandwidth to create this issue's, it's.

A

Fine, it's like the one I had I had noticed and not submitted, and it's like I should submit issues when I notice them.

C

B

C

B

Also heavily I think that in general will be an agreement that github wishes something useful for the plug-in side, sort of food and drink. You say, oh.

A

Yeah agreed wholeheartedly great: now we are nearing the end of our time. Are there other topics that need to be addressed in this movie? I'll just leave the data in the end, without doing a review during this meeting. Okay.

A

All right, I think we're at a point where we can call it an end to the session thanks very much everyone for joining, looking forward to our progress and google season of docs and more yeah. Thank you. Everybody have a good weekend.