The confidence and blessing to make Django documentation improvements

Speaker 1: Okay, should we start? Okay, let's start. Okay. I need to be standing here, I expect. Hi everyone. Um come don't sit at the back down there. You're charging your phone, yes. It's good because uh maybe you you need to be talking to each other because this is uh uh a workshop. So thank you for coming. Uh coming all this way to Vigo to see me. Some of you had to take Buses and trains and planes and so on. Let me introduce myself. I am Daniele. That's what I look like on television. I work at Canonical, I'm a director of engineering. I was a Django project core developer when that was a thing. Still a badge of honor. How many of you have encountered the

Speaker 1: Diet Axis documentation framework or heard of it? A few of you. Okay, so that's what I'm responsible for. I'm in the business of documentation. open source community contribute contributor. Oh um I was with Anna and Dawn. We organized the DjangoCon Africa that took place last year. Anyway, this is not about me let me Tell you a little bit very briefly about Canonical. We're hiring, I'm hiring specifically about 120 technical authors. to work on documentation for hundred for Ubuntu and hundreds of open source software products, also hiring developer relations engineers, CMS. documentation platform engineer, engineering directors for community and

Speaker 1: um developer relations, all kinds of Python people. So I'm going to share all this with you in a minute. So you can have access to those uh to these slides, but there's a document I want you to read first just so you can navigate our system. Oh sorry, I should be in front of the microphone, I forgot. So you can navigate our system with the best luck. But I'll I'll talk to you about that afterwards. So who 's here because they're interested in working on Django documentation? Okay, well I hope you mostly are because this is kind of what that's about. So if if if you're not interested in that, you're probably in the wrong place. And if you want to leave quietly without looking to embarrass now is at home. Because the longer you stay, the worse it gets So one of the problems, let me point this here, because I can't I know

Speaker 1: one of the problems that we have in open source software Especially on something like Django. You know, Django is pretty conservative about what it accepts, has very high standards for everything. Everybody who puts in a pull request or makes a suggestion has to go through several iterations with Natalia before it can be accepted. There's Natalia, our Django fellow, who is you know the gatekeeper of quality. So it's difficult. You think, oh God, this is I'll never get this done. This is too difficult. So um two things, the confidence to do it and the feeling, the blessing. Yeah, it's This is the right way to do it. I've been permitted or empowered to do this. Where do you find those two

Speaker 1: things? to work on something. Well that's what this session is about here. So confidence it's not about knowing What it must be like. This is the thing that in one of the lessons I'm trying to get across in documentation to the entire software industry is that knowing what the final thing should be. Is not necessary for us to work with confidence. All we need to know are the rules. And the rules are actually quite simple. I know the rules. I can tell you the rules. Okay? So with those rules, which I've actually gone to the trouble of writ writing down for you.

Speaker 1: You can work on documentation on the Django documentation because the Dang Django documentation tries to follow the same rules too. You can do that work with confidence. And as for the b the blessing, this idea that you're empowered or entitled to do it, Daniela said it was okay. Okay. I I will give you the blessing, okay? And that's the best blessing you can have when it comes to documentation and especially on Django. Isn't that true, Natalia? It is. It really it really is, okay? With my blessing, you you can do it, okay And also, just as an addition, I'll be here during this at least the first day of the sprints. So if you're here at the sprints and want to do something, want to actually try and get it done, I'll help help you get it done. Okay.

Speaker 1: So um that's the uh again um I'll share the slides so don't try and um find that now that's the week We're going to be using the Dataxis documentation framework or applying it. And it's not the time for me to explain that to you. But anyway, the best way to discover it is through uh using it. So I don't know how well you can read things at the back. Maybe you want to come to the front. I'm just going to show you very briefly these rules, but then I'm going to give them to you to read by giving you the link to the slides, okay? So look. There are four kinds of documentation and there are four kinds of documentation in Django's documentation. There are tutorials, how-to guides, reference material, and explanation. Those are all four and the only four kinds of documentation that we are concerned with. Okay. Each one of them

Speaker 1: is correct when it follows certain rules. So for example, in a tutorial, well you establish a tutor-learner relationship Sorry, I'm sorry for the people online. In a tutorial, you focus on the concrete and you avoid abstraction. Um in a tutorial you tell the re users what to expect and to notice and so on. Okay? So there they're more these are not the only rules, but they're ones that I want to give you right now. A how-to guide is a different kind of thing. A how-to guide, I want you to address a real-world situational problem. I want you to Assume user competence. Oh by the way, I should have pointed this out. When you're dealing with a tutorial, ask yourself all the time, what

Speaker 1: do you want the user to learn? I said a tutorial has this relationship between a tutor and a learner. Who's in charge? Who's in charge in a tutor-learner relationship? The tutor. Who's the tutor? You are the tutor when you're writing documentation. It's not what the user wants to learn, it's what you want the user to learn. Yeah? So that's what you must be thinking. What do I need the user to learn? Yeah, no use asking them. What do they know when they're doing the tutorial? In a how-to guy, what is the user trying to achieve? That's the question that's in front of you. Oh, it's not about the machinery. People, you know, have well these things you'll you'll start to see them.

Speaker 1: How-to guides are all about click do this, click that. That's not a how-to guide. That's Instructing a robot how to press buttons. That's not interesting. So a how-to guide is about somebody's purpose, somebody, what somebody wants to achieve. In a reference guide We want to be consistent and precise and accurate and complete. We're looking for neutral description. Oh, we're following the structure of the machinery Yeah. If the machine if the machinery, if the code, if you know, if there's a module with a class and some methods inside it, then the structure of your reference documentation should be about first the module and then the class and then the methods. So it's like when you have a map, there's a one-to-one relationship. And you ask yourself, what information

Speaker 1: does the user need? And the final kind of documentation, explanation, is what the user needs to understand It makes connections, it draws parallels. It's interesting actually. It's the only kind of documentation you can read in the bath if you're a normal kind of person. And it's for the user who's not actually working at that moment. It's for the user who is away from the work. Okay, everything you need is going to be on. That link. So um is that the if you can't oh I'll put it on Slack. That's probably a better thing to do, right? Okay, let me so I can stop

Speaker 1: um Sorry?

Speaker 2: Yeah, the access to it's not open. You need access to it open.

Speaker 1: You need access. Okay, right. There's always a technical problem, isn't there? Um let me come out of this and let me Maybe one and yes, okay, so first of all, let me share this with everybody. I thought I'd done that. No, I hadn't Anyone with the link can view it. Great. Okay, so try um opening that again. And then I'll also paste the link into Slack.

Speaker 2: Can you read things from the back there? Yeah.

Speaker 1: Okay. So um That should open this document and then the task sheet, which I'll look at with you in a moment, is it is another file. Okay, so um let me send that link into Slack. Um is there I don't see a channel for it. Oh, let's put it in the general channel. Okay. Sorry for the spam, everybody. Uh thing for the workshop silence. Okay. There you are. Good. Alright, they'll forgive me, I think. Not now. Right, let's go back to this.

Speaker 1: Okay, so what I've got here is a little spreadsheet. Okay. And we're going to use the spreadsheet. So I'll uh you you should have access to it. You don't have access to it. Shut I wonder what I have shared then. If I haven't sh I know I was sharing something. I don't know what it was. No, no, but before I did this, I was preparing. It must have been, you know, my blackmail letters or something. So anybody, everybody's got access to that now, so you should be able to jump in. Okay. So what we're going to do here is We're going to you, not me, you, because it's a workshop and you're doing the work, you're going to identify some things in the documentation

Speaker 1: that You think could be improved, and you're going to say you're going to say where it is, you're going to say what the rule what you think the rule is. We'll talk about that. You'll talk about the particular problem and then you will suggest an immediate next action. Okay? And if I like it, I will bless it. Okay Yeah? That's how I bless it. How we bless things nowadays in spreadsheets. Then if you want to if you're going to do it right now, you can put your name in there and when it's done, it's it's it's done. The wise it's not this and then it will be done okay but everything that you put in there you know refactoring the tutorial that's not

Speaker 1: no Changing a heading or a paragraph or a word, that's the level at we oper at which we operate, okay? You can save refactoring for some other time, but Do the tiny things, really small things. Okay. So um here is Writing your first Django app part one. Okay, so my two examples came from here. Um oh I did I um I've actually got a Google document. Of it here so I can But we don't you've all got have you all got a computer? Does anybody need to sit with somebody else to share a computer? So Please do. It's better if you work with other people. So sit next to somebody and you can argue with them and so on and talk to them. Yeah? Don't sit on your own. Um

Speaker 1: Let's let me I want to take you through two small examples. And then I want your examples. Okay, so let's actually start here. Um what were my examples? They were ah yeah, okay, so um here's the j how many of you have done the Django tutorial? Yeah, and how many of you have actually really done it and not just putting your hands up so you don't look bad from talking to others? Yeah, okay. It's it's actually, I think, a a really pretty good tutorial I don't think it's the best tutorial in Django. I think in some ways the Django Girls tutorial is a bit better, but

Speaker 1: maybe we can actually improve this, okay? Who has any opinions about the Django tutorial? Who who who's done it? Yeah, what did you think? Sorry. Good? There is I don't miss it at the moment. Okay. Okay, so uh for the people on online, um beginner is saying that uh she found that there was too much information in the tutorial for a beginner's needs, correct? Is that right? Yeah. Okay. Um did you do the Tango girls tutorial as well by any chance? Yes. How do you how do they compare?

Speaker 3: Just linear single example of how to build jungle process. Very good and then Then I went to the Django tutorial and felt off.

Speaker 1: Okay. All right. Anyone else have comments about the Django tutorial? Good or bad? Maybe from more intermediate perspective. I found it will be a little bit too verbose

Speaker 4: necessary. which will be used in the future, like managers for instance. So it feels like the it emphasized on simplicity rather than like maintainability of the code. Which means if you are just starting with this project with the test button.

Speaker 1: Okay.

Speaker 4: Cool. Your

Speaker 1: your perspective is kind of the opposite of I don't know your name, sorry, but yeah. Good. Anyone else? Okay. Um I d I did this tutorial, but I did it um in about 2009 or something and and s some of it is is still very much the same as it was then. And um Here we are creating a project. Where should this code live? Can you can you read that by the way? Um by the way, if you're doing this on yours, um make sure you're looking at the development version. Where should this code live? Now this was interesting for me back in 2009. If your background is in plain old PHP with no use of modern frameworks, you're probably used to putting

Speaker 1: your code under the web server's document route. And that made sense in 2009. Does anybody think that makes a lot of sense nowadays in 2024? How many of you started off using plain old PHP? No, I mean we're in a different world. Look how much space this thing takes up on the page So in here, by the way, can you can you read this at the back? Or I suppose you're in the document even if you can't read it on the screen. Yeah, yeah, okay. So I think I've identified there I've identified the thing, okay. One of my principles for a tutorial, if you look at the uh rules that I shared with you, rules for a tutorial.

Speaker 1: What does it say? Don't distract with information. Okay. I think that that section that we just pointed out is distracting the user. I think it's distracting the user with something that is a not even relevant and B confusing and C not even connected to anything that they're likely to know. Do you agree with me or does anybody disagree? It's good I have to have at least one person. Normally I plant a stooge in the audience to disagree. But um does anybody disagree? No, okay. It's okay to disagree with me. So what do you think we should do? Any suggestions? What should we do, Natalia? Uh I don't

Speaker 5: know this there. Not sure if that helps.

Speaker 1: You you're not sure? You do know why? Okay, what why is it there?

Speaker 5: Because the reload need to be good

Speaker 1: Oh so sorry, you're you're you're offer excuse me, you're offering me why as an as an explanation rather than as a reason. Yeah, yeah. Okay, yeah, as a Uh that uh uh that's that's how it happened to be there in the first place. Why is it there now? Is there still a good reason now? No, I don't I think we should simply remove that section. In fact, I mean I would go further than you. I would just say let's get rid of it completely. Do we need it anywhere in in Django's documentation?

Speaker 5: easier to be understood, particularly in the template system. If you understand that this there is a link with PHP

Speaker 1: Yeah, but I I I think that nobody I think that hardly anybody nowadays is relying on a link with PHP. Yeah? S I saw a hand up at the back. Could say I was thinking

Speaker 6: maybe we we look at what is the purpose of the nodes. Is it to let people know about how to organize your code. Maybe you reword it about making more about educating people about organizing the code. And then take up

Speaker 1: Well, I think this question, where should this code live? That's a reasonable one. But I think the answer should be pretty much anywhere in your user space. Yep.

Speaker 2: So basically just a lost sentence.

Speaker 1: I I I I that would be my suggestion. You had a question?

Speaker 2: No, is your point like remove because nobody gonna use old PHP and and that's true but e even nowadays if you had still want to make this correlation with PHP you would have to make it with a new influence work and what they are doing.

Speaker 1: Yes.

Speaker 2: Like like

Speaker 1: exactly. So

Speaker 2: frameworks also use a question like like HP. Nowadays PHP is not what it was. I know because I became in PHP. Like it's what brought brought me to the but nowadays it's not

Speaker 1: so now I think that the immediate next action should be simply to remove that section. Maybe we can slightly modify that, like for example, keep what that last line of it, or maybe find another place for it, or something. But that would be my suggestion. Okay Simply remove it. There's another one in exactly the same section where it says let's look at what start project Created. Oh look, let's look at what start there it created that, okay? That's nice. That that's good. Remember one of the rules is tell the user what to notice and expect. You know what the user should not be having doubt, the learner in a tutorial should not be having doubt. And neither should you, by the way. You should know exactly what's going to happen at every stage, yeah

Speaker 1: And that's good. I can think, oh yeah, mine looks like that too. Um when you uh you're doing your first Django tutorial, was it really helpful for you to have Did an entry point for ASGI compatible web servers mean anything to you? No.

Speaker 3: um the the the tree with my size manage my size and I think that what's pleasing to me and maybe this if we can correct is to command documentation is that the project is named my site and the the the file which has all the init and the settings and the ASGI and the this game, the URLs, that's like the main project, is also named my site. And that was really confusing to me because they didn't add the application, which was named out in the web or API or whatever. And it's confusing me what what is what? So

Speaker 1: Yeah. Um

Speaker 3: sorry.

Speaker 1: No, but you you're uh you're right, because we have I think that's going to be a bigger question than documentation, though, because of the way the template for creating uh projects works all together in Django. Yeah.

Speaker 3: It's just Or what actually does.

Speaker 1: I'm gonna ask you to hold the come back with that thought in about two minutes time, okay? So um Maybe this one is more controversial than the first one, but I think looking at this, yeah, now remember we're dealing with somebody's first exposure to Django. I think that in a tutorial we should get let the user get on with learning by doing, not interrupt Their flow by making them look at and under read things that they don't even understand. Okay? So I think, in my opinion, the explanation of all those files that are created literally doesn't mean anything to the new user. And they are things that they don't need to know either.

Speaker 1: If they need to every one of those files that they need to know anything about, we will tell them at the right moment in the rest of the tutorial. So I don't think that that information itself is bad. I would suggest, in this case, not deleting it, but moving it somewhere else in the start project documentation if we don't have it somewhere else. Yes, you had a a question or want to say something. Make a reference Prince, that that's what I would like.

Speaker 5: We'll explain what these files mean later.

Speaker 1: That's a good idea. Um links. Links are an excellent way of saying, okay, there's some more information over there. You don't need to look at it now, but if you want it, you can go and find it over there. Yeah. Fair enough. Yeah.

Speaker 6: This is useful. Uh depending on work if you partner work work with Jangor or any other first time at C and D's it's it's too much.

Speaker 1: Yeah

Speaker 6: no but everything is close. Yeah but it for example you come

Speaker 2: from or spring uh or any of the frameworks i think it's easier to start understanding from the beginning uh what are the similarities or where to find the files that So

Speaker 4: I would move that to some uh to some page that's about the start project command, for example. Maybe there's a reference or explanation guide somewhere that we could find a better home for it.

Speaker 1: Maybe it exists there already. I didn't even check.

Speaker 6: I just wanted to make a comment that I think links are very helpful, but uh they can also be a bit overwhelming if used to much so as a beginner i think you just want to get something done and then if you're uh overloaded with links you just Maybe go down the rail it's not.

Speaker 1: Exactly. I mean if we're if we're going to put a link there, then we need to say something like, if you want to know more about this, then go and see such and such. Okay. So Does my reasoning so far seem more or less um reasonable to you? Yeah. Okay. Now what I want you to do is think like me. And I want you to be, well, I can see you're in there already. And I would like you Sorry, to formulate the thought that you were expressing a couple of minutes ago that I asked you to hold for a moment and maybe we can put it in this document now.

Speaker 1: Everyone's everyone's eyes are on you. Yeah. Um which part of the documentation was it? Can you remind me? Was it Oh it was about my site and my site. Why why are there two why are there two full directories, two folders called my site? Is that right?

Speaker 3: they're called the same and to have like I don't know maybe on the diagram of parallel of of some case

Speaker 1: okay.

Speaker 3: It's it's gets it can get confusing really fast

Speaker 1: Okay. So we're still in, actually we're still in um, I'm gonna copy that because we're still in let's look at what Start Project created. So um If you look at the rules that I shared with you for a tutorial, is it can you is one of these um Is it encapsulated in one of those rules, the principle that is behind your thinking? Just because it's not in these, this is not exhaustive, by the way, so um I can think of a good rule here, which would be

Speaker 1: reassure the user about potentially confusing things. Yeah, uh you know this is not meant to be an exhaustive list because um it would be pages long. So I I think that that's you know um reassure the user about Potentially confusing things. The reason I want you to think to to put the rule in is because I want you to be thinking in terms of rules and principles. Okay? I want you to be doing actions but always thinking in terms of rules and principles. Because rules and principles scale and they make things consistent. That's how we can all work together if we have share the same rules. Okay about confusing things.

Speaker 1: Okay, and the problem is that we have two my site directories and I I think you're right by the way. It's not just that you found it confusing. I know from experience that other users do. That's a simple empirical fact. It doesn't care. By the way, this is one of the here. As the author of the tutorial, I know what you need to learn. But I have to have my eyes on you the whole time to understand what you're actually learning and what you're confused by. If I write the tutorial and then I never see a watcher user using it, I've only done half of my job. Yeah? So we have two points and

Speaker 1: Uh we often see users confused by that. Now your job is going to be to the immediate next action. Okay. Now, I mean the immediate next action. I do not mean the five-year plan for improving this section of the tutorial. I mean something you could do in Half an hour or ten minutes or something like that. So what I want you to do now is write that in that box, okay? Um good. So other people have started writing things. This is what I like. Okay, the word patch. Django used to get proposed changes as VCS patches, but nowadays we work with GitHub and PRs. A new contributor does not need to know nor understand what a patch is. Let's go and find that piece of the documentation. Oh

Speaker 1: this is okay, this is it. Someone's diving into here. I I I is it I sensed your hand at work there. Good. Okay. Writing your first patch for Django. Okay. So this is not even in the tutorial. And Um oh there was some you were starting to type something in there about the Yeah, okay. So I mean actually Think about the I mean this sounds to me more like a problem rather than a principle. What what is the principle? Yeah, is it is it a tutorial it is a tutorial, isn't it? Again, that one. Is it yeah but isn't it? Oh by the way, tutorials, I mean

Speaker 1: The jack tutorials are for learners which is not the same as beginners. Nothing to do with beginners. Who arrived here by airplane? Okay, so your pilot at some point in the next couple of years is going to go back into the training, will go into the flight simulator to practice, I don't know, engine out landings. They will be in a learning situation, in a tutorial situation, in the hands of a tutor. Is that for beginners? No, it's not But it's still a learning experience. They're not landing a real plane, they are having a learning experience. So tutorials are nothing to do with how advanced or difficult things are. It's just about whether somebody is there because they are learning or because they're doing work.

Speaker 2: But you do you do have like Different you can have a tutorial that is aimed for beginner that you don't have a requirement of pre -knowledge.

Speaker 1: Oh look you can have tutorials at any level you like But what's what distinguishes a tutorial from something else is not how advanced it is, but whether the purpose of it is getting work done or learning something. Yeah. And whether there's a tutor present. I don't again, I don't think you see, the f tutorials are so difficult. I could have filled up three pages with rules for tutorials, but I think Eliminate don't be confusing. Again, what you identified is similar, it's similarly anachronistic

Speaker 1: to the PHP example, isn't it? Yeah So I think that should be uh um yeah it's not it's not the same problem, but it's related. Yes, you've got a hand up. Oh you were trying to my rules. Good. I love it when people like rules. Okay, second and third rules. Yeah, so yeah. Yes. Okay, yeah, okay. Hmm. I used to be a high school teacher and I I I'm I'm inclined towards thinking that teaching is not actually possible. All you can do is provide the conditions under which somebody will learn Everybody thinks they can teach. Everybody is desperate to teach. I'd love to teach you, but this is why I want you to do things and not listen to me.

Speaker 1: Because you won't learn by listening to me. You will learn by actually putting things in those in in that s sheet. Yeah. So I don't think we should try to teach. But we can provide experiences. We can set things. Has anybody here taught a child how to ride a bicycle? Well you didn't. The child learned by themselves. You just provided the conditions of the learning experience, yeah? However desperate you were for the child to learn, I must I assure you that um you weren't able to transmit it. Their body had to learn it. Yeah? Even in programming, insane. Does that help? Yeah. Good. Okay, let's have a look at our sheet.

Speaker 1: No no that's fine. It's good to tell people what they have to do. But but but the idea that I can transmit the learning into That's not gonna happen. Yeah, it's not gonna happen. And this is why if you look at the Django tutorial, there's so much explanation in it, because the author, you know, wants the Purse, I want you to learn. I want to make sure you learn. But that's not how people learn. They only learn by doing concrete things. Good. This is looking really good. Okay. So um where is Oh yeah. Django you so the problem is Django used to get proposed changes as VCS hatches, but nowadays work in GitHub. And the principle don't confuse readers. Could you say with um

Speaker 1: Say something about with anachronistic terminology or something like that or with out-of-date terminology. I think that's good. Yeah. Okay, look, these are these are looking really good. Um Um explain what each node means and does and maybe draw a diagram.

Speaker 3: Sorry. You revised it.

Speaker 1: You revised it.

Speaker 3: Yes.

Speaker 1: Okay.

Speaker 3: Just don't use just don't use my sign name.

Speaker 1: Yeah, what do we need to do in order to do that, in order to have two separate ones? We'd have to add another. I

Speaker 3: just give it a different uh as I understand it the the the the folder that contains the project my site

Speaker 1: Um no, because we uh here we are we are in we're just anywhere in the directory. Then we run this command. And then it creates both of those. And I think there is a way to add Natalia, you're probably more up to date on this than I am. Isn't there a way to add a uh an extra option to this so that the inner one has a different name or am I misremembering that? Okay, I'm misremembering that. It's always going to create them with the same name. Yeah. It's it's it's because of the way the Django template works. You think it's possible to create them with different names?

Speaker 1: Yeah.

Speaker 4: Directory attributes that you can pass.

Speaker 1: There is a name oh there is a name and directory attribute. Okay. There we are. So now we're making life complicated for ourselves. Now we've got to make decisions about what's more difficult for the learner to have a simple command like that and then explain it or to explain it or to show the command with the extra argument and then explain that.

Speaker 3: And specific. I'm I'm I'm sort of on on the spectrum of how to make my life more difficult. I'm on the more difficult.

Speaker 1: Okay.

Speaker 3: I'd say have have have them the difficult virginity.

Speaker 1: Okay.

Speaker 3: But that's me.

Speaker 1: No, no, that's fine. What I would like you to do is put that down as a suggestion in the sheet. And then Just because somebody's put a good stress in the sheet doesn't mean we'll necessarily accept it. We'll still have to talk about it. We'll have to talk about it with Natalia. What are the other implications of this, okay? But at least it's there. Even if the solution turns out to be different, you've still specified the problem and a possible way forward. Yeah? Let's go back to okay, so we've got that was m that was mine, that was mine, that was Why do we have

Speaker 1: oh somebody it's it did somebody add this because they want to have a different solution? Is that why that one's there? Who added line number five? Um Is that yours? About plain old PHP. About remove the PHP. That's yours.

Speaker 4: Yeah.

Speaker 1: Okay, so you're proposing a different solution from mine.

Speaker 4: Yeah.

Speaker 1: Okay, no, that that's good. What I'm going to do is I'm going to move that up. there okay and what I will since it's exactly the same issue what I'm going to do is I'm going to um I'll make it the same. I'll merge those two, okay, so that we can s we can see that there are two alternative options for that, okay? Good, thank you. Changing the port. Uh who 's is who's the one about changing the port? Are you okay go on then? Okay, tell tell us why why you why you said what you suggested about that. This is changing the port. Um

Speaker 1: Sorry, can I ask you to can can I ask you to talk speak up? I

Speaker 5: think it's really button.

Speaker 1: Okay, so in the tutorial it says how you can change the port and you think that this is potentially confusing the user with something that's I think it's just irrelevant more than confusing. I think it in itself it's simple enough, but it's an extra little burden of a little cognitive burden. Yeah? And the user does not need to change the port in this tutorial. And if they do or if they want to, they already know enough that they can find it out for them themselves. Yes? I agree. Uh I agree with I both of your solutions would seem fine to me. Good And then we've got Natalia's patch, okay.

Speaker 1: Starting um starting the development server at um etc. So whose is that? Yes please. Speak up loudly so everybody can hear you.

Speaker 4: We have a lot of sections below which explains like we are running development server. So this is the name of the section. But like we want what we want to have is a running of the server. application and if there is like three paragraphs up to the point when we say okay now what you see is actually shows the application is running.

Speaker 1: Where is it? Yeah okay it's here yeah

Speaker 4: we do something and we doesn't have light anything So and then we try to elaborate on what it actually does line by line, which is okay. But the essence of this is actually that line which says like application is started. like my suggestion was to just highlight it with a uh with a bold text saying okay out of everything if you decide to look on this this give you that the maximum information we needed this this

Speaker 1: okay so things like your migrations that's not relevant for example yeah

Speaker 4: we go in about And like okay, my question's learning. So what is it really?

Speaker 1: Okay. So your suggestion is highlight the line indicating the application is running in bold. So you'd you you're suggesting to highlight that line, I guess. Uh these two lines.

Speaker 4: Yeah, because the first one doesn't read the EPD that application is running. Just before.

Speaker 1: Um yeah. And um that's adding stuff. Normally I like to take stuff out of documentation. Not put stuff in. Okay. But I think that especially since I'm I'm sorry, I don't know your name, but since you suggested removing something immediately there, I think that we're still on net zero. So yeah, I I I think that I think that I think that's good Yes, I think I would agree with that. The principle is right. By the way, how many of these changes are rocket science? None of them. How many of them seem so small that you'd feel embarrassed to put them in a pull request? Yeah? Don't be. Don't be. I refactored the PyTest documentation a few years ago and I said to them, look, sometimes

Speaker 1: I need to do this in tiny little bits. Sometimes I will send you a pull request that is only changing a single title or a word. And they said, yeah, okay, we'll do that. And I just would I just fired them off. I could it made it very easy to work like that. And you're here at the sprint, I'm here, Natalia's here. We know you might be doing that, okay? So don't be embarrassed. We should get less embarrassed about that, especially in documentation. Because we are doing things step by step according to the rules. If you do things step by step according to the rules, you will get to your final destination every time. When you walk up a mountain, you put one foot in front of the other in the correct way, and eventually you'll get to the top.

Speaker 1: Yeah? So, um yeah, I think that I think that's good too. Look, oh there's so many this I tell you what I'm gonna do. I'm gonna start blessing some these was I like them. Okay. So um your suggestion about removing the PHP reference book, putting it somewhere else? I'd accept that. You know, maybe if you're not sure which is best, come and talk to us and we'll decide on which one's best. We have two my site directories. I'm not going to bless that one just yet because I see you're already discussing it with Natalia, so that's good. Changing the port. I I yes, that has my blessing. There's a blank line here, which we don't need. Let's delete this row. Natalia, you don't need my blessing, but I'll give it anyway to remove the word

Speaker 5: patch. Right word? Because I'm not convinced it contribution. Oh what? Writing your first contribution contribution but but we have a lot of places that mention patch so I'm not bad

Speaker 1: yeah uh are you here to throw us out for the next oh no okay okay just Oh there's a break now. All right. How long do we go? Okay. How long do we go on for? Okay, all right, okay. Yeah, okay. So um But Natalia even if look even if Your immediate first action is not perfect. What's going to happen when you make the pull request saying um writing your first pull request. Somebody, there are lots of other intelligent people in the community. Somebody say, oh Natalia, you said pull requests, but I think contribution would be a best

Speaker 5: word. Yeah ,

Speaker 1: so don't worry. The next action is not to get to the top of the mountain. The next action is to take is to put your shoes on and start walking.

Speaker 5: Okay.

Speaker 1: Okay. So same with um your suggestion where we're not quite sure if it's the right one. Put your shoes on and start walking in that in that direction. Um I'm sorry, I don't know your what's your name? Marina. Marina 's suggestion offered an alternative suggestion over here. Now, I don't know. I can't tell you which of these two suggestions For the same thing, which where is it? These two suggestions is the better one. But If you could sit all night waiting for God to come into you in your dreams and tell you which is the right one. But so far he has never done that, not for me anyway. Yeah? So make a pull request and then it's there.

Speaker 1: If there's a better solution, you know, if there's a simple change that makes it better, somebody will tell you, take the first step. Because it's still an action in accordance with the rules Um so yeah, I like that. Uh I don't know why we've got these blank lines where people trying to distance themselves from other people's comments or something. Uh starting the Yes, I like the one about highlighting the line. And you know, highlighting the line could literally mean highlighting it in bold, or maybe it means That we just say notice the line above. That's another way of highlighting. I don't care how it's done, but again, we're on the road. Um database setup. Lots of text on how to set up a different database.

Speaker 1: Is this in the tutorial? Yes, it is. I mean who thinks that setting up a different database is really handy for the person setting up their first No, it's not. Whose idea who's Well well done. Good. Okay. Move it. It's probably somewhere else. At most I would add a link saying, oh you by the way, you can use different other databases in in Django. I that's all I would say. Yes, it has my my my blessing as well. More blank lines. I'm gonna just have to get used to the blank lines. Um Who's made the one about writing your first view? Write your first view. The user does not see what the direct impact of adding the URL path is. It's either a shy person or someone who's left. Oh, it's somebody online. That's why my thing went.

Speaker 1: Yes, Alex. You raised a hand, you're online. I don't know if I can hear Alex or you have to write something. Oh, it's in the chat. Okay. No, okay. Um I'm not sure why that went made a noise, but I don't know who made the comment about um uh Writing your first view, I um I think that part is I'm not sure exactly what part is meant by that. But I think there's a lot of stuff in in the views section that's um could be got rid of.

Speaker 1: What about this right? Is the person in the room here? Yes, gone. Okay, but

Speaker 2: you've got an immediate action, yeah? If if on Saturday you're in the switch, you start sitting down and doing that And then you'll talk to somebody else and maybe your first action will change. But now when you arrive at nine o'clock on Saturday morning on the screen, you open your laptop and think, I know what I'm going to do, because it's written down there. Yeah? So you'll be single, what should I do? You'll you'll know what to do. You've got it. So good. I th I I think you know that gets my

Speaker 1: um what about uh pop-ups for quick explanation? People follow links Uh who's who made that suggestion? Tell me more about why you made that suggestion. And we

Speaker 6: have just about links. Yeah. So that people should you know focus on where they're um

Speaker 2: I certainly synthesize with your problem But on this occasion, I think it is your problem. Um I'm sorry to say that. As the You know, um I think we have to be very strongly opinionated when we're doing tutorials. And I'm gonna be opinion about that

Speaker 6: Yeah, that's yeah that's not a single thing.

Speaker 2: I think I think the way we word links can be useful. If we say if you need to know more about such and such, go and see that, that's good.

Speaker 6: I like photos.

Speaker 2: You like hot dogs?

Speaker 6: Yeah, finished.

Speaker 2: Yeah, I don't think we have

Speaker 1: even have the option for it right now. So that They wouldn't be the next action would be to build pop-ups into the Django documentation would be a longer thing. Okay, sorry, w somebody was trying to ask me questions here. Stop sharing. Oh just stopped sharing. Oh I see that's what the problem was. Okay, good. All right. Um so I I I'm I'm sorry, I'm not yeah, I I don't normally use that language, but yeah. Okay. Um Confusing users with SQL migrates. Um who's who's who's is that example? Not someone here? I I'm gonna only choose the ones of people who are available to talk about it. Um

Speaker 1: Read part two at the end of the page. Why would you link to the next page if the button isn't right underneath? Um that's Right here. Um

Speaker 6: That was me.

Speaker 1: That's you.

Speaker 2: It's I I agree with you that it looks a little bit unnecessary. You know, so I said people want to teach but they can't teach. Another often mistaken thing that

Speaker 1: people say about teaching is that repetition is the best teacher. Have you heard that? It's not true. Repetition is the only teacher So on that basis, I think I wouldn't mind repeating that. Also, it reinforces the idea that this tutorial, I want you to go it through step by step, beginning to end. So I I I would actually need that one.

Speaker 5: And also an electrical access accessibility. You might have a bigger phone in the league too far away for a mobile the league might move somewhere else because of CSS and stock.

Speaker 1: I think I I I think there are reasons for keeping it That doesn't mean that your reasoning is wrong. It's just that in this case we I think that we should jump a different uh way. Yeah. Um does anybody have one they want to talk about or want to ask me about, by the way? Yes, please. No the this one.

Speaker 6: Yeah, the U term URL conf in the write your first view. I think it's it's Yes.

Speaker 1: I think the first time we run into URL conf it it calls it that. What the hell is URL conf?

Speaker 6: Yeah, there's no explanation they just mention what it's yeah what it's about.

Speaker 1: Okay. So um I know that uh I said ruthlessly minimize explanation. That does not mean never explain anything. You take you 're teaching your child to make scrambled eggs in the kitchen and you say wash your hands because we need We always need clean hands when we touch food. That's the explanation. You don't discuss germ theory with them. Or maybe you do, but that's not gonna help. They'll go and do something else, yeah. So I think we need we do this because of that, or

Speaker 2: this is a this is this is a knife, this is a sharp end, end of story, no history of Japanese knife making compared to European knife making. making and so on. So yes, I I I uh what what are you going to propose?

Speaker 6: Um either discard the term your completely because it doesn't pop up anywhere else in the tutorial.

Speaker 2: Okay, I think the word I'll I think I would accept an immediate next action based on that if the word brief comes before the word explanation Okay. Or very brief. Yeah, that sounds good. Anyone else? Um I'll

Speaker 1: I want to show you one of my least favorites favorite parts of this. It's this stuff here. Um you the path function. Oh, the path function is passed for arguments. I mean, I've been using Django for I don't know, maybe fifteen years. And If I want to know that stuff, I will look it up

Speaker 2: in the reference. Yeah. Actually I don't want to know it. I just want to copy things down and copy it from an example and and change the name of the variable so it still works. That's that's the reality, yeah. But after you that's how people learn by doing things from examples, all this bullshit about you have to acquire the concepts, that's shit, okay? Um This absolutely has to go from the tutorial.

Speaker 1: It has no place in the tutorial whatsoever. So

Speaker 2: if anybody wants to

Speaker 1: mark that for summary execution, I'll also accept that. Because it's

Speaker 2: it's absolutely

Speaker 1: useless information to a beginner. It's frightening and it takes up space. then do

Speaker 4: the possible cases from the example code that we know so they will stick only to one

Speaker 1: example cases in the tutorial. Exactly. Sh sh where where where is an example case in the tutorial? and

Speaker 4: name right so the other one is is that one with the include

Speaker 1: sorry you'll have to um yeah

Speaker 4: exactly this this one

Speaker 1: Okay, well um the Django tutorial is an interesting thing where it it makes you change things actually quite a lot in the URLs

Speaker 2: Dot pie file. It starts with a really basic case and then it says, oh no, look, now you've done it that way. Here's a shortcut which is nicer. And then it does it again. Um and I admit that I'm in two minds about that. I'm not sure whether it would be better to go to the simple working case and say this is how we do it straight away and then if somebody needs to know the more general pattern they can look it up Or are they learning something useful by going through those steps? That's the question I would ask because when we're doing a Um when we're in a tutorial, the question I should be asking is, what do I want the user to learn?

Speaker 2: I'm not convinced that the different ways of doing it are really that useful. But I think that other people in Django might disagree. So that would that would need to be a conversation to have. But that doesn't stop you proposing it as a first step, by the way. Yeah? It it would start a conversation. Are we out of time now? I I've I've I'm completely confused about what time we should be stopping. No, no, no, we are not. It's just loud are there because last go was cancelled. No worries. The last talk.

Speaker 1: Oh right, okay. Okay. Right. Okay. Okay, so I've got until another ten minutes to go. Okay. Oh we're over to we're over time. In that case, we're over time. Sorry, I I can't keep you from your break or or whatever. But look There is a lot in here. I will look at this.

Speaker 2: I might um I should have asked people to put their names on it so I can find them and uh ask them what to do. But look, if any of you put your name in that column, you don't have to do it right now this minute, but if you think you're going to do it while you're at DjangoCon, just put your name in that column. Say I I I want to do this tonight in the hotel or on Saturday at the sprints and then come and find me and we'll look at the the right way actually to do it. Yes.

Speaker 6: I was uh wondering w what was the process of uh validation uh of it for the documentation.

Speaker 2: What's the process for a pull request searching in Django?

Speaker 6: Yeah for the documentation.

Speaker 2: Exactly like the one for code. It's exactly the same. And I kind of avoided all that question about how to do the pull requests and so on because you can find that Natalia's here. She she can help you with that. I I didn't want to get into that. I wanted to get into the thinking behind How you will go about improving something in in documentation. So look, these are You're all highlighting, I'm not in every single case, but in most cases I see things in here that I think are right. I think I agree with the problems. I think that you're identifying real

Speaker 2: principles, real rules that make sense. And Fewer of the uh immediate next actions I wholeheartedly agree with, but that's that's always the way it is. That's normal. Yeah But they all look to me like good plausible next actions. You know, remove the link and rewrite the sentence. How concrete is that? That's a change that something could do in half an hour. That might be somebody's first pull request. first patch into general and it would be a step up the mountain according to the rules and if enough of us do that one after the other we will get to the top of the mountain So I'm going to stop there because I'm over time. Sorry.

Speaker 2: Thank you very much. I hope that some of you will actually do something with this. That's why we're here. You know where to find me? I want to talk to them about maybe this or canonical or jobs or anything. Okay , I'll be very happy to talk to you. Gosh.