Ceph Docubetter, 2 Nov 2018

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Ceph Docubetter Meeting 2018-11-02

Description

https://pad.ceph.com/p/Ceph_Documentation

A

How's it going.

B

Good I think we are the same set of people from last week. That's very consistent.

A

B

B

Did say something we weren't able to hear.

A

Maybe we can use the chat.

B

After meeting well all figures out his audio.

A

He just left I think.

B

I just want to rejoin and see if it works, so I was able to hear some background.

B

Alright, though, I think welcome to the second meeting of the doc, you better and know, I think we are PR is like almost set and just waiting for some blessing, slash reviews, yeah.

A

A

Yeah so I think the reviews- yes, we're, not really clear. What needs to be reviewed. I mean it's just like.

A

B

Think stages out this week for the last two days, so have him review it once and then it should be good. No.

A

I think that's a good idea when, when I first revamp the schedule page, he had several comments and then changed his mind. A couple times. I think there he may. He may actually want it. Some something changed and then once that's approved, we'll need to do back ports, and that can probably so obviously we'd want to do mimic and luminous.

A

Is it possible to still do backwards to the other branches to like jewel.

B

Not um you know we are not really back boating, regular fixes to jewel on clearance. It's like really really important, though I wouldn't worry about duels, so I think mimic and luminous should be good, and once this gets much I can take care of the back boat in you know what role.

A

Do you mean you mean, don't back port at all or only back port going forward.

B

Make any luminous I said: oh I,.

A

See um yeah I mean I think so our next phase would be to start to deal with I. Think. Last week we discussed tackling some of the search engine issues.

A

But that doesn't completely solve the issue of knowing what you're looking at, and so that's why I'm kind of curious like if we can make an exception to back port a documentation, change the things like jewel, because that's what would it enable those banners to be on the page that say like this is not supported anymore right.

B

Okay, for that, for those purposes, it might be worth it. Okay, I'll I'll figure out how that can be done. What's the best way to go about it, but I understand the motivation behind doing it, though, like further out with the back boats team that we have, but at least we know, we need it for the immediate two releases.

A

Okay, yeah yeah, definitely and then.

A

Yeah yeah I guess that the thing is like the search engine. Optimization is not gonna they're, still, like probably a million links out there that are like pointing to old old things like okay. Alright, that sounds good, so I don't really have any update on the search engine. Stuff I have a list of suggestions that had been mentioned in the mailing list, but I just haven't been able to find time to like research.

A

This stuff there's like.

B

I, just briefly went over it. I believe this is the suggestion that we thought about.

A

Yeah, it seems to solve part of the issue, so there is definitely this notion of this canonical reference, but I think it needs to be done in conjunction with several other things. So there's the one. Is this canonical thing another? Is that I think when we use the canonical thing we're also gonna maybe need to change the redirect. So when you go to docs.google.com.

A

Gens to just like, don't even index certain things and we can use like a regex to say no, maybe ignore everything except master, mimicked luminous- or you know stuff like that or maybe ignore all the BRS I think we can get several different techniques together to like create a pretty robust solution. Okay,.

B

Where does that that extra five aside.

A

B

Start yeah yeah. It.

A

Would be at I I think it's on a per domain basis, so I think it would be doc. Cf comm, slash, robots.txt, okay,.

A

So we'll need to also.

A

I guess this will be the point where we will need to maybe bring Alfredo back in to talk about how the site's deployed, because the robots.txt will need to get deployed correctly and then we'll need to update the redirect. Now.

B

I understand that box: no okay, okay! So let's do that then. For next week we can give Alfredo a heads up that we would like him to be at least here on this meeting, and then maybe he can give us more ideas and talk more about how that thing works. It's going to be useful for everybody to hear about it right.

A

B

Okay, so, and once we figure that part out, we also need to add links users to be able to switch between versions.

B

A

A tackle that in the next no.

B

No, that that might be the third thing to do: I'm just trying to order things in my mind. What are the like the next thing and then the next thing you could do if anybody's interested or knows how to do these kind of things they can just pitch in right. Yeah.

A

B

Ended up to adding a little bit of stuff to the project speech. I can try to share mice in ants Oh how that works in yeah.

B

Okay, are you able to see my screen.

A

Yeah, it's the blue gene. Oh yeah, yeah I, see it okay.

B

Who's ready, not.

A

A

What you say is.

B

This better I just zoomed in a bit oh yeah,.

A

It's fine, okay,.

B

So and when the idea is that this part, so this is the work flow that you explained last week about editing on github now the other option is like, let us say for whatever reason, due to lack of time or like lack of expertise or whatever user just wants to report our documentation bug he or she could just come here, and this is what I've added in this first card explains how one can go about improving set documentation.

B

First, one just describes cost point here: just describes how you can just go and click on the edit on github link, and then you can just create a PR, and this is only going to work for all the relevant branches that we care about and for other ones, you'd see the warning on the like a red label on the tops saying that this documentation is unsupported.

B

The other way to report documentation bugs would be that you could just use this UI here or this platform here. To just add a column or add a card and just write in whatever you observed was a bug.

B

So if you have a github account and you have github credentials, you should be able to access this projects page on safe / self, on github and the way you can do, it is just add a link to the doc that you found a hat above and then you can just describe the bug in maybe you're a couple of sentences. Just saying that okay, this config option does not make sense anymore, or there is a minor thing.

B

Like I I observed a spelling mistake in such and such you know page things like that can just easily be reported using these two fields linked to the doc and describe the bug, and the final case is that for those of our users who do not have github credentials per se, they will not be able to use either the first option, which is edit on github, because that creating a PR and doing other stuff requires github account and even accessing this projects page.

B

So this person with no github account will have a view only access here you can just go and see, but not too much sure so for those set of users. You can just click on this etherpad link that I've added here and if you just click here, it opens a document like this, and this is just a blank sheet where you can put in like examine examples, the same thing linked to the doc and describe the bug, and this does not require any kind of github accounts or any kind of access.

B

This is open to all. So this is going to be the easiest way for anybody to come and report. But, yes, we would encourage people with github accounts to user, like github accounts to use the first or the second way of reporting bugs. And finally, what I would like to emphasize on even on this projects page, we would encourage only relevant ACEF release, bugs that means master, mimic luminous and if you find bugs in older versions, I, don't think we want to go and fix them now.

B

So please ensure that you use it for the right purposes. I think that's it.

B

I mean this can further be narrowed down to like different components, as we see people using it, and if we see that this is just becoming too cluttered and it doesn't make sense to have any everything in the same column, we could just create more columns for people, and you know maybe all the luminous bugs could be in one column, all the mimic could be another and we can do in whatever way we want, but we at least want this platform to be used by people in the first place, so I think that's all I wanted to share in terms of all kinds of you, users and all levels of documentation.

B

Bug reporting that you can use bits F now.

A

B

Like it, what a bull is Gaurav is your thing working now, your audio working now you're, muted anyway. So, okay.

B

I think he's just typed something I have a question. So this is a question from Gaurav. He says: can we have the trackers related to dog fix in one eater pad with some small description so that if someone wants to fix them? Okay, yes, I I- think our God of AI with the project's page that I just I can link it again. If you want it's the second.

A

B

No I think he's talking about like one place where, let us say a newcomer who wants to contribute to Stefan, who wants to go and fix, bugs and see them and go and start fixing them. Is that right, Connor I think that's what you meant.

B

Let me just assume that's what he meant and I can just go through how people can do that. Let me just share my screen again so.

B

If we just go to.

B

Steph you see there is a section called projects here. If you just click here. This takes you to all the dog active doctor projects that we have on github and the first one here is documentation.

B

This is the page that will redirect to and it will tell you what options you have and what we are suggesting is we use the rest of this projects page to go and report documentation bugs. So let us say, let me go and do in write an example. So I will just create all the memory.

B

Bugs this creates a column now, if I want to add a card, I can probably go and add a card here or I can just start. Oh and edit, this column.

B

Okay, how do I add that here that.

A

B

Not letting you add a card like this.

B

This is just saying, add a column. This.

A

Is at a card I think right: okay,.

B

So let's say: okay, that's how we do it yeah. So let us say this is the section for all the mimic bugs so I just come here and stay linked to talk and I'll have let us say whatever link here and describe but- and this will say, config option.

B

Xy z-- is not relevant anymore, so let us say this is what somebody reported now you'll be able to see this card here and any fresh contributor to that can just come here. Look at this create a PR link that you can go and edit your and then you can edit this note. Let us say there was a PR to fix this and you can just link up PRS. This is the PR and then once this gets resolved and much we can always delete this note from here.

B

This is the whole workflow that we want to use for new users to come and contribute just look at this projects page and look at the bugs that are open link of the yard that fixes it and they are all. So. The idea is that we we, as deaf developers, will go and revisit this document on on a regular basis to combine some cards which may be like can be fixed in one pull.

B

Request may be right, so there is some stair like two or three mistakes in one page in our BD we will just say: okay, just whoever is gonna pick. This these two three or gods and create a PR to fix them together. It just optimizes the whole process, rather than just creating one line, changes and stuff like that. So, okay, I see that you have understood what I was trying to say and who I hope that this is gonna, make life easier.

B

Alright, I guess, is there anything?

B

That's okay, no worries! God. If you have more questions, you can just type it in the chat or you can write a follow-up email or something I.

A

A

Maybe it would be useful to make like I just found a bug in the mimic documentation, and maybe we could like just make a card there.

B

That's what I was trying to do, but I couldn't think of any bug.

B

B

Demo, that one and that will be awesome, you can.

A

Share your screen.

B

A

And then I think it would be nice to have like a bug in the column. It's.

B

A sample people yeah yeah.

A

So I'm gonna add it, but we shouldn't fix it. We should just leave it.

B

Sure, as far as as long as it's not very crucial for us to fix.

A

Some people may even just say it's not a bug, but we can leave it in there anyways. Okay. What can are you seeing anything.

B

Seeing a set volume, page cool.

A

Alright, so is it um there's a bug that I think exists is that this outline over here? Isn't it doesn't make any sense like there it's clear that there should be some structure to this mm-hmm right so, like LVM has like documentation for its sub commands and so does sort of simple but they're, not like structured in a hierarchy. So it's really kind of confusing about what this list of things is trying to portray to me.

A

I suspect that this might be a result of like a kind of a lack of being able to go like another level deep, but we could go ahead and add it and then see if anybody cares to look into it.

B

A

A

I guess we can create this and then maybe I'll add some more details.

B

Add a link to this. There.

A

B

A

B

I just want people to just add to at least two things.

A

So the navigation.

A

Outline on the left side here doesn't show the hierarchy. I, don't know how to spell that.

A

It doesn't show the hierarchy properly. For example, the children elements of lbm are at the same level as the children as.

A

Lbm and simple okay I mean I, think that should be enough to get British nobody's. Looking at this, they get it and they can say like it's like the docs, don't support another level or.

B

Yeah this would be like this is not like a trivial fix right, it'll, be some set volume person who's just going to get involved and be able to see how what's the best way to fix it. But if it's like a very small minor issue that somebody encounters or maybe with some very directly link, is not working or something like that that you can't just be fixed frizzy, so I think this makes sense and that you know the more people start using.

B

It will get a better idea about how we can classify these and how we can just maybe also simplify this may with one simple column which says this is for newcomers, and you know basically categorization of simple bugs medium or high.

A

Yeah I think it's not clear to me that you can I think you have to you, can categorize them. Maybe we'd have to use columns. If you turn them into issues, you can attach labels to them, but I don't know if you can do much to one of these notes unless it turns into an issue other than just moving it around between columns.

B

The other thing, I know that you can probably do is you can assign labels to them and those labels will be in the PR linked to them these these cards.

B

If you go to some other project, if you just go to the crimson project, for example, and just look at how that is being used to be able to.

A

So those labels are attached to PRS right. Yes, yes,.

B

A

So I think, like.

A

Yeah I mean we would yes I guess it just depends on if wanna categorize things without first having create PRS. That would be a problem. Yeah.

B

Then the only thing you can do is use columns for now.

A

Yeah, this is sort of the downside of not using github issues, because you can turn these into issues and then you could attach labels to those. But we have that disabled for the Ceph project.

B

But well then, this is better than nothing. So, let's just start with this, and if you really think this we have seen bottlenecks here, then we can always switch to a better platform. Okay.

A

That sounds great.

B

So there's another question in the chat says: will this project be updated with trackers which are currently open? Okay, so we could do that. I mean there is a way to report. Yeah I know there's a way to classify bugs in the in tracker dot, safe, dot-com documentation. We could do that as well. I am NOT saying that one can replace the other, but I'm just saying that doing it in both places is just going to be redundant and I know.

B

The tracker has a workflow which you have to first create a bug, and then that sends an email to everybody. And then you know you have to follow the whole thing and also I, don't think you can, and you could probably associate other issues to one tracker issue, but until unless they are like really related, it doesn't make sense, because you're solving two issues with one PR doesn't make sense to relate them in a trapper issue.

B

So the idea is to you know if there are simple things that do not need to go through tracker dot safecom, we might not choose to use that for documentation purposes.

B

So yeah. That's the answer to your question: caller.

B

Well, have you been sharing yours.

B

If it is more exciting than talking about documentation, well, yeah interesting.

A

It's not about documentation, yeah.

B

B

Is there anything else we want to discuss? We have two minutes I.

A

B

The two dues for next week are pretty clear: we need to get this PR merged and we need to reach out to Alfredo and try to get him. I know it's gonna be a bit late for him on Friday evening, but if he can just make it for at least the first part of the meeting he'll be great, and then we can start working on the next step, which is getting the right links. Getting the relevant links in the search up.

A

A

Don't this is pretty good.

A

The documentation is now better.

B

At least that's what we're trying to do.

A

Did anyone I I, just realized I, didn't fully read John's reply to our email about feedback, I.

B

Think he was pretty happy about it. You should just request a review from him. I.

B

See that as a plus one for me, yeah.

A

That's I was, like it says, awesome and then I was like. Should I keep reading.

A

Yeah so I think he's basically saying so I'm talking about some of this stuff that is gonna in our next steps.

B

We don't have any more questions. We in call it a day thanks for joining everybody and do guys next week. Okay,.