Let's become confident about Django documentation - right now!

Speaker 1: Thank you for thank you for inviting me. Thank you very much. Welcome everyone. Um it's really lovely to be here with you. I've been looking forward to this. I'll do a very nope. I will do a very, very brief introduction and I'm just going to see if I can drive my computer properly to um share a couple of things with you. So let me share my screen. I just want to introduce myself. I know that most of you, I think um know me already I guess yes there's we'll show you my screen. So I'm Daniele. I work at Canonical as a director of um engineering I've been involved in Python and Django

Speaker 1: for uh I can actually say it's a long time now. So uh in my case it's about uh nearly 15 years. Um I'm especially involved in the African Python movement. I'll be in PyCon, Namibia in two weeks from today. And um the other thing I am is a software documentation disciplinarian. And that's what I want to talk to you about today. Actually I don't want I want to reduce the amount of talking that I do because I love talking and that's what bad teachers do because instead what I want is for you to be doing uh some stuff instead. So um I I see that most of you are are retiring behind your um cameras, turned off cameras, which is fine

Speaker 1: because that that saves energy and bandwidth. But it's actually good if we make this into a discussion. So feel free to interrupt, ask questions, we'll interact. And if you don't volunteer then I will choose volunteers of my own for you to do things. And what I would like to do in this session is not try and I don't really believe in teaching, but what I want to do is to for things to be different afterwards, I want to give you confidence about touching Django's documentation or indeed documentation in general but we're looking and we're concerned with Django so that's what I want to be different afterwards. If afterwards you feel Oh yeah, uh I can do that and I'll I'll give it a shot, then I'll be really um

Speaker 1: pleased. That that's my aim. Um I do need to do a tiny bit of talking before we get started, otherwise um uh uh just to give it a little bit of context. So um in In documentation, the kind of documentation that we're dealing with in Django or software generally, we are dealing with documentation that serves the practitioner in a domain of skill. So um somebody who uses Django is Exercising a skill. Somebody who's learning Django is learning a skill. It's a craft or practice, Ancient Greek

Speaker 1: technique. Which is where the word technology uh comes from. So it's always about skill, or you could call it practical knowledge. So it's knowledge that involves the hands as well as the mind. So it's a certain kind of knowledge, practical rather than theoretical knowledge. It's got lots of different names. So the challenge for documentation is to serve somebody who is a practitioner of skill in a certain domain And the test of quality is whether documentation is adequately serving the needs of those

Speaker 1: users. Um now very, very briefly, in every skill Sometimes we're on the left-hand side, sometimes we're on the right-hand side. Sometimes we're acquiring the skill. We're learning, we're becoming good at it. We can call it being at study. Sometimes we're working, we're being good at it, we're applying the skill It doesn't matter whether it's roller skating or Django or flying an aeroplane or driving a racing car, it's exactly the same. Sometimes you're in the study mode, sometimes you're on the right-hand side in the application mode. And sometimes in the skill The stuff that's important is only in the head. Cognition, it's matters of truth, like, you know, um

Speaker 1: Facts. But sometimes it's in the realm of the body, of action, of doing things with the hands. And every skill incorporates both those things. So I've shown you two dimensions now And they split the territory up into four needs of the user when I want to learn. the skill, when I want to get something done, when I want to know something and when I need to understand something. And these are all quite separate things. For example, knowing and understanding are really uh distinct uh from each other. But what they give us is this, and this is my um map of documentation.

Speaker 1: And I think it's a map of documentation, a complete map of documentation, because it is it is a complete map of the needs of the practitioner of skill. You can see there's action on the top and cognition on the bottom, there's acquisition on the left and application on the right. And they give us four different kinds of documentation which correspond to four fundamental needs. And I'm going to stop actually stop right there with the theory. We can come and I've, you know, I can talk all day about this um theory and and we can say more about it. But I want to stop talking about that now and I'm going to try and come out of this and go to here. So now you should be seeing you are screen sharing.

Speaker 1: Yes. But what What are you seeing from my screen sharing? You

Speaker 2: see Mastodon.

Speaker 1: You see Mastodon? Great. Okay. So um this was very timely because this popped up. I don't know if you can see it well enough. I'm not quite sure how to improve it so it's better for sharing, but maybe if I do um Sorry, I'm dealing with so many windows that I'm not quite familiar with. Let me put that one over there.

Speaker 3: I think control plus might help or shift plus.

Speaker 1: Yes, yes, that's that's a good idea. Okay So this popped up on Mastodon the other day. I don't know if any somebody else might have seen it. So this is from Jeff that I know some of you know that there was um A little note in the tutorial about the Django tutorial about race conditions, what they are, and then a link to say how you can avoid them. And Carlton, whom I think you also probably know, said that's one of those interesting things that's also irrelevant that doesn't need to be in the tutorial. And um Carlton has quoted me from the DearTaxes website that In the tutorial, your job is to guide the learner to a successful conclusion.

Speaker 1: There will be many interesting diversions along the way that you can ignore. I think Carlton's right. I think the tutorial would be better if that note just disappeared. And I think Jeff 's also right. If you're going to face race conditions, you're probably going to have other things by your side that help you deal with them. And I don't know who Fancy Sandwiches is, but fancy sandwiches had an opposing view that this is an important concept, which is true And sudden people mightn't want to know it up front, which is also true, and suggest putting it in a short section at the end of the tutorial.

Speaker 1: And I disagree with that actually. So I think what's actually happened is that Carlton actually has indeed removed it. And I just posted that I think this morning that I think the only thing I care about in the tutorial is for the people following the tutorial. to become comfortable and familiar with the concepts, the tools, the workflows and terminology. And I don't need them to do anything more. I just literally want them to be comfortable. I don't even want them to remember anything. So I'm going to stop now and ask where you would have voted on on this puzzle or this dilemma

Speaker 1: what you would have done, what your instincts are. And you don't have to agree with me either

Speaker 4: Hi Daniela, this is uh Ryan Chieley. I I saw this come across Macedon as well and and I I agreed with with your sentiment that it did seem to be out of place and the sentiment that both Jeff and Carlton had had made as well. And actually I'm I'm struggling with trying to get my team to understand and implement Dietaxis where I work. And I felt this to be super helpful in terms of having some conversations. uh some conversation starters with them as to what goes into two tutorials and what doesn't go into tutorials. So I think that like these kinds of conversations are super important because it can kind of help have a real world example that people talk about and then something is done about it. So

Speaker 1: yeah.

Speaker 4: Anyone else?

Speaker 2: Um Roman. So I I do agree. I think for as a beginner it's um It's not useful to direct them to another section to have them go down a rabbit hole, which might lead to other rabbit holes that they end up kind of losing track of what they were originally trying to do. But I guess the only thought I have is whether the example itself is perhaps not the best designed because I don't know if it was originally designed as like a because sometimes I see tutorials put in deliberate gotchas So that you experience certain things and that you

Speaker 2: can talk about certain things. So I don't know if perhaps uh w it it shouldn't have this potential race condition anyway kind of thing because I feel like sometimes people look at the tutorials to find or like the things inside the Django Docs to find the best possible code kind of thing because it's in the Django docs. Um so that's the only thing that I think is is maybe

Speaker 1: uh

Speaker 2: but I agree that I think this concept is not it's too soon for the very first tutorial in Django to bring bring across this concept.

Speaker 1: You you said an important word there which is experience because the tutorial is all about the the experience that you give to somebody the learning experience and the tutorial is all in the action part because When anybody is learning a skill, any skill, they learn it by doing it in the hands of a teacher a tutor that they can trust. That's why it's called a tutorial because it literally implies a tutor. So I don't I definitely don't like gotchas because that undermines the trust. I think that visn we want comfort for the user.

Speaker 1: So I think giving people alarming scenarios about things that could go wrong that are not going to go wrong now. It's not relevant. In the tutorial, in the teaching situation, we always bracket off the rest of the outside world to keep to make it safe. And that applies, you know, if you're teaching a child to ride a bike, to make scrambled eggs. There are all kinds of things that could be known and need to be known eventually for that person to be really good at this skill, cooking or or cycling, but they don't matter now. They can come later. Right now we want to give them something that's an a point from which they can They can always get back to that point and say, oh yeah, I know how to

Speaker 1: I know how to do the first stitches if they're a medical student. I know how to make the admin work in in Django. and they will take the next step. So this is the distinction between learning and teaching. We always want to teach and I think the only thing we actually can do in a tutorial is give people an experience that they can learn from. Okay, let's move on. Let's look at um let's look at the first no wrong one. Okay, so here's the writing your first Django app part one. I want to start by by looking at this um uh tutorial with you and what I want you to do is talk you through some of my thinking about it

Speaker 1: and then I'll show you another page in the same in the uh of the tutorial and I want you to do the talking. So if I've got it right. You're seeing my Google document, I guess. Yes, good. Okay, so here's writing your um Django application part one. I've just dumped it into a Google document. Is that large enough for you to read or do you want me to make it bigger? Okay. Um what I've done is marked things that I think are important. So let's learn by example. I love it. Let's, every word in that sentence is great. Let's, we , let us together What we are concerned with is learning

Speaker 1: and by example. That's people, that's how our human brains work. We see lots of different concrete examples and we generalize from the concrete particular examples. Whereas what teachers always want to do is give people the universal picture and you know the general picture, the overview. And hope that people will have it stick in their minds. It never will. It only comes out of concrete things. Oh, I saw a hand up.

Speaker 2: Yes, sorry, Danny.

Speaker 1: Yes, please interrupt rather than putting a hand up. So please please interrupt, yes.

Speaker 3: There's a request to make it large

Speaker 2: Yeah.

Speaker 1: Oh a quest request to make it larger, yes. Um yes, yes, of course I can. Um I think that is that will that do

Speaker 2: Yeah, I I I think so. I think so.

Speaker 1: Um yeah. I don't this stuff on the side doesn't seem to get any bigger, but Oh maybe there's a different um zoom in. Yeah, maybe that's that zooms everything and then okay. Okay, I hope that will do. So that's great. That that's exactly what a tutor tutorial should be doing We'll walk you through. We're doing it together. It's you're in the room with the student or the students in the room with the teacher. It's going to consist of two parts, an admin site and a public site. That those words, right now, I'm a beginner in Django, they just bounce off me. This is this is the tutorial author. reassuring themselves about what they're going to be writing. This is not for the benefit of the person reading it.

Speaker 1: So I don't I don't like that. I would delete that. We'll assume you'll have Django installed already. Great. I'm assuming this. You have to assume some things in your tutorial, but I'm telling you what I'm assuming So I'm making sure that you're seeing, you're expecting what I'm expecting too. Oh yes, this is a small detail. Please head over. Now there are many English speakers for whom please head over will be a very unusual construction. So simplify it C. And you don't need to say please. It's it's uh it's just not really necessary. So that's a basic thing

Speaker 1: I like this this is a kind of aside about naming. Now Maybe we could make that sentence a tiny bit shorter, but it raises a little flag, waves it in the air, and then quickly moves on. And I like that. It doesn't It tells us that this is because you know perfectly well that somebody creating their first project is likely to call it test, for example, which is where they're going to run into trouble. This I I'm sorry, you I've I've I realize that it's a bit hard to see what it's um what it's saying there, but this is the stuff about if your background is in plain old PHP

Speaker 1: I see absolutely no reason to keep that in there. That's background information that's just getting in the way of what the user is doing. This on the hand on the hand is great. Let's look at what it created. This is what you should expect. Oh, you didn't see it. Now you know that something's a bit wrong. On the other hand, I can't I would give money if one person in ten actually read any of that They can see in front of them. They just want to go to the next step. Let's verify. Let's do it together. Verifying, that's also really good. You will see. Brilliant. That's exactly what we need to be saying to the user Ignore, don't worry about that, reassurance. Um I like that

Speaker 1: And you might think, oh well, just a minute ago we were talking about um production and race conditions. Why are we worrying about about that question now? Again, it's just a little flag. Um and sometimes these things You just have to be a good experiencer of documentation. I still remember this from the very first time I used Django all those years ago. And there's another example further on. So sometimes these little flags do help something, even if somebody doesn't exactly dig into that, that, that, that. That's fine.

Speaker 1: It's a little slag about the bigger world out there. It's like saying to somebody when they're making with your child in the kitchen, be careful, because the handle of the pan will be hot. Oh, this is something This is great. This is a little bit snippet of explanation that just highlights these two words which are very overloaded in our discipline and dispatches them really quickly. And then it spoils it with that, imported it as its own top-level module. You know, I would have to sit down and think before I tried to explain what that actually meant to someone. So This is for the reader, and that was not for the reader.

Speaker 1: That was for the writer reassuring themselves. What is a view? It's not actually, we don't even know what a view is here. And I think that it's invaluable, you know, if you're going to teach somebody to make scrambled eggs, at least they'll have eaten scrambled eggs at least once. Beforehand, oh yes, sorry, I didn't see that question. I'll show you the the let me make this document um publicly accessible, of course. Yes, I'll uh it's anyone with the link. Done. Oops, and then I can copy that link and I'll paste it in the chat. There you are.

Speaker 1: Yes, sorry. Did I miss any other questions?

Speaker 2: No.

Speaker 1: Okay, so can somebody here say in one s one short sentence what a view is that would make sense to somebody doing their very first view? A view is a what?

Speaker 5: I think it's um a thing. Well not a thing. It is something that connects the information uh that you okay never mind i had a good analogy but i used to say it connects your information with To make it feel ah crap. Never mind, ignore me. I used to have a good explanation for this.

Speaker 1: I i it's it's it's not easy, okay? But if somebody is going to improve this tutorial. And I think I I I think my notes here are actually rather decent notes for somebody who wants to improve the tutorial. I think that's a challenge that somebody's going to have to solve. Okay. Nobody said documentation was easy. And coming up. Go on.

Speaker 5: Sorry. The few is the code that collects all the data that you want to show to the user and makes it available to the template Still a bit too technical, but we're we're getting there.

Speaker 1: Um I I I like the language of collecting and showing. Because that's language that I don't need to do extra cognitive work to understand. I'm not even that bothered about whether you're completely correct or not. That's not so important. The important thing is that I my understanding advances a little bit. So I think that would be a good starting point. Yes, Mo, you've got a hand up.

Speaker 6: Um I think it's is is my micro uh okay because I'm seeing a lot of weird lines. Can you hear me?

Speaker 1: Yes

Speaker 6: Okay, so I I think it's safe to assume that the reader knows what a request is and a response is since like this is Django. So it can something like it's thing that processes the request and serves the response is will it be okay or or not in this case

Speaker 1: I liked the language of collecting information that you want to show or something like that. I like that. um already in in in the language of request and response, those feel to me like things that we need to Those things, not not explain them, but use them in sentences that will help somebody understand them That's the thing that we've got to become good at doing. Um you don't explain a knife to somebody who's learning To cook, you give them experiences of the right knife with the right foods and the right way of holding the knife. And that's how they pick it up.

Speaker 1: Not through explaining it, but through Doing something concrete that's connected to something they already know. Okay. Anyway, that's a challenge. I'm not we're not gonna solve that here, but uh what I'm saying is that that is this question, what is a view? is a real and quite challenging question in documentation. I love it.

Speaker 2: Some other versions. So there is A view is the presentation layer of your project. It's responsible for mangling with back and forth between users and backend. And another one is a view is the structures of what a page needs to do when a user interacts with a URL. Oh sorry, a view is the instructions of what a page needs to do when a user interacts with a URL.

Speaker 1: I like that one as well. I like the way that that one uses terms that are not presupposing familiarity with other things So anyway, I don't think we're going to solve this now. It is difficult, but that's that's a good conversation for somebody to have and to knock those ideas around. It's worth keeping some of those. You can put them into the comments, I think, actually, in in this document Um it chops off. What is, you know, that's been in there, I think, for a decade or more. It chops off. Somebody could pay attention to what it might mean be like to experience that um

Speaker 1: that sentence and not really understand, not already know what's going on. So I didn't like that. And then we get to the end. My least favorite part of the uh that tutorial. Look at this. Um here is the um table of contents of this page We've got one, two, I think uh we've got about nine items in there, and four of them are these path um methods. That's it in the tutorial. So why are they so important? They take up nearly half of the table of contents. And they take up where is it? They take up all this. Look at them.

Speaker 1: Not one person is has read those. I'm not saying it's not good information. It's just not information for here and now. Because There's nothing we can do with those and the tutorial is always remember it's in the action um part of our our our world it's about doing things Okay, so those are my thoughts. You've got this document now. Feel free to take it and argue about it. And maybe I'm wrong or maybe I'm right about some of these ideas. But I would like now us to do the same thing with another page. And let's do it with this one. I'm going to share this one with you as well. But this time. I'm going to do much less talking and you're going to do the

Speaker 1: talking. Oh, you should be not viewers, you should be editors. Okay. So I'll make you an editor of the other one as well. Okay, let me share this link with you. Yep. Okay. So, and you can be as rude as you like about this one because I actually wrote this tutorial all those. uh years ago um the the the testing one so that make that one editor done okay so let's go back to this one so we're all in in uh I want you to look at this sentence by sentence and share your thoughts, put them as comments, talk about them here. And I warn you, if you if I don't get volunteers, then I'll start choosing them.

Speaker 1: So Okay, I'm gonna ask you a question since nobody's um what is wrong? Here it is, it's this one here. What is wrong with The first part of um sorry, wrong wrong one Writing your first Django at part five. What is wrong with a large part of this document?

Speaker 1: Why is it bad? What did I get wrong So from what we were talking about, you were talking about earlier of tutorials are about action.

Speaker 3: and doing things. This starts with a question and answer of providing information and background on a number of things rather than getting into writing the test immediately. That's my guess.

Speaker 1: Yeah. I remember writing this about 11 or so years ago. And basically this is me explaining. Testing to myself. This is me reassuring myself. Okay, all this stuff. It's not bad stuff, but I don't think it lives here. I would just simply remove it Maybe there's one thing that I would keep. I think there's something about um Why do it right now? In the middle of the tutorial?

Speaker 1: And I think that I think that might be the only thing worth doing. Why why are we doing this? Let me reassure you why this is important. The rest of it, I think that stuff actually could go and be placed somewhere else in Django's documentation. I don't think it's bad stuff. It's just that it doesn't belong here. Does anybody disagree with that? Does anybody feel that it needs to be there to help somebody who's doing stuff with um sorry wrong page again with tutorials or with testing

Speaker 6: Well a c a couple of minutes ago we were discussing like how to explain views to to the reader. So we try to be verbose about what a view is So so uh I think we can somewhat extend that logic here to a reader that like might not be familiar familiar with um like tests and so to give to try to be more verbose before we do stuff like we did in the view, but here it's um it's uh another sub sub-article or a sub -thing But but yeah, we we we should try to be more verbose

Speaker 6: since we we established this from the beginning. to make sure we're on the same page or something like that?

Speaker 1: I think that, no, I think I would actually disagree with you about, I don't think we want to explain what a view is. I don't think we can explain what a view is. The m all we can do is give somebody a bit of a handle on it. That's the maximum that we want to do. So that When they next hear the view, they think, oh yes, it's that thing that collects data and then share and then shows it. That's not really an explanation. That's just a little handle, a little label that somebody can that's small enough for somebody to keep in their mind So

Speaker 2: I think I think with this test stuff that's at the top And I get why it's the reassurance. I think it's come with some background that a lot of people don't write tests. And so Why do we go through a tutorial and and show how to write tests? And it's a little bit of like encouraging people that they should write tests is is here. But maybe that's covered by that that why and then and then it can be linked further off for

Speaker 1: Sarah, you mentioned um driving lessons, yeah?

Speaker 2: Oh yes.

Speaker 1: Okay. So if your driving instructor says, okay, Sarah, now we are going to practice this. Are you going to say, well, why do we have to practice that? Is that thought going to occur in your mind?

Speaker 2: Probably not.

Speaker 1: Probably not. And even if it occurs in your mind, because of the situation you're in, here's you the learner and there's the instructor, you won't say it. You might think, why am I doing this? But you'll just go along with it. And and then you'll find at the end of the of course I needed to know that. You'll realise why. Um Only teenagers who are learn having driving lessons with their parents say, why do I have to, you know, why do I have to know this? Everybody else just obeys the teacher, and that's part of the teaching contract. Imagine you were having your first flying lesson. The instructor doesn't say, okay, I'm now go into a lengthy thing about why this is important to know. We're going to do this. I'm the instructor. I'm in charge.

Speaker 1: I'm the authority Your my part of the bargain is to keep you safe. Your part of the bargain is to do to follow my instructions. So I would get rid of all of that stuff. Um I think the rest of that Document is actually pretty good.

Speaker 3: There's uh Mariga has uh a question.

Speaker 1: Yes, please, question

Speaker 5: First my compliments to Tim. You practiced really well. Yay. Um I was thinking with regards to the difference between giving a a little handhold about fuse and explaining testing. Would you also consider different approaches between general programming concepts like unit testing and Django-specific concepts like Fuse?

Speaker 1: That's a good question. And um I think we would need to agree on who our audience is of this tutorial. Is it somebody who's already got some programming experience or do we think that it's somebody without any? So for example in the Django Girls tutorial, they make that really clear what they expect of the user. And I think that works brilliantly because they that image of the person who's on the other end is always in their minds. So the answer is I don't think it matters which one you choose, as long as you have thought about it and that everybody who is contributing to the nine different parts of the tutorial also more or less agree with each other.

Speaker 1: Yeah.

Speaker 5: Yeah, I was thinking maybe sometimes people have just written really good tutorials about a specific subject. or have very good official documentation, that it makes more sense to just add a note like, do you want to learn this in depth follow this other link or maybe add some nomenclature page at the start of the tutorial like these are all the terms we're going to discuss and here's some useful links if you want to know more.

Speaker 1: I much prefer your first suggestion of just putting a link to oh you want to know more about testing go and read it over there so somebody can go and do it. Yeah. Yeah, I think that's good. What I what I do what what I think I got right in this is that it tells I said examples, examples are fantastic for your or for your reader. They are concrete things in front of them and they will use the examples to synthesize the general cases. They will abstract from the examples. That's what we that's what we're good at. Um we don't need to. You don't how many of you explained a triangle to a child None of you, but every child you know who can more or less speak

Speaker 1: knows what a triangle is because they abstracted from examples. And that's what we do all the time. So that's one thing that's really good. The other thing that I I the thing that I like I think I got what did well here it tells a really nice story. So narrative draws us along. We are really good with narratives. We can remember You know, ask a 12-year-old to repeat the entire plot of Lord of the Rings to you and they will do it because we are fantastic at dealing with narrative. Um so yeah, um I think there's some opportunities there. Now What should we do with

Speaker 1: all this stuff? Should we just throw it away or could we do something else with it? Well I think we can actually do something quite useful with it. So There's a lot of material in the tutorial that I think should be removed. But we've got a topic page for uh triangle and testing oh yes i'm going to show you a slide now if i can find the right way to do it i think uh where are they I did have it. Ah yes, here we are. Look. This is

Speaker 1: how Django's documentation is supposedly organized. You know, this is not quite true. This doesn't This is broken down a lot. But India Taxis, in the framework that I very briefly introduced to you earlier, there are tutorials which are action for learning, how two guides which describe action for applying your skill rather than acquiring it. That's the distinction between a how-to guide and a tutorial. And Django has them both. Tutorials that take you by the hand step by step. The instructor takes you by the hand. The how-to guides assume some knowledge, but they're for doing actual work. They're not for learning. They're for applying to your work

Speaker 1: Then in Dia Taxis we have the stuff that happens or that's for for for the at the cognitive rather than the act uh action level uh realm rather. The facts. That's what reference is. It describes the machinery. It's where you look things up There's no action implied in it. It just tells you these are the facts. This is a function that does this. This method requires these arguments and so on. And then the topic guides are for background information and explanation. They help fill up our picture. They give us knowledge. They're not for. . executing our skill, but for acquiring it. But they're also not about action, they're about cognition. So we've got

Speaker 1: these four types of documentation built into Django already. And one of them is, indeed , the testing topic, which is Not that one. Um in fact it's this one. Testing in Django. And it's very short. So I think maybe this is that explanation page where we could put some of that stuff that I didn't like in the tutorial. I think that could go there quite happily. But look, there's a a second topic page, which seems a bit odd. You know, why would you have two explanation pages about the same thing?

Speaker 1: You've got the introduction to testing over here. um sorry here and then you've got this other one which is supposedly the testing overview but if you look at this one Um sorry, if you look at this one, tell me if you think that this really is explaining anything or if it's something that you would use when you are actually writing tests Anyone

Speaker 1: anyway.

Speaker 6: Uh this is Apes actions. Love things are uh are actions, not like knowledge

Speaker 1: Yeah, I I I I agree. Yeah, sorry, I'm flicking around because I'm trying to get my pages in the right place. I uh uh I agree with you. I think that this mostly looks like a um a how-to guide. I'm gonna what I'm gonna do is just to try and manage my windows a bit I'm gonna share a third window with you this ideas one So uh let me make that available to everybody. Anyone with a link can become an editor. Okay, and let me share that one here. So Yeah. So I think that this looks more like a how-to guide, mostly. Um It says, you know, look at this.

Speaker 1: The document is split into two primary sections. First we explain how to write tests and how to run them. This is. This is where you'd go if you wanted to uh helping hand while uh running your tests. Um Now you'd have to go through this and find out, consider for yourself, is everything in here really a how-to guide? Because often what happens is that stuff gets mixed up. There might be some stuff in here that's not really a how-to guide. Does anybody have a suggestion what actually to do with this document What would be the first thing that we could do to make this

Speaker 1: better?

Speaker 6: Maybe copy the the other stuff in the tutorial uh and move uh the the practical stuff there like switch them the The things.

Speaker 1: Sorry, okay, so we've got some in the tutorial, we've got some We've got some kind of cognitive stuff. We've got some cognitive, we've got some stuff for the head, and then we've got some stuff for the hands down after it, yeah, in in the tutorial. And I think this the the explanation stuff should come out. So that's one question that we should have we should solve. Where should we put this? Um So what what were you suggesting? Can you repeat that for me please Mo?

Speaker 6: Um yeah. Okay, sorry. I was saying that we maybe can move the cognitive stuff to the have to and then move the practical examples. uh to to the tutorial because it's uh it fits there better.

Speaker 1: Ah okay good no thank you for that that that's good so let me share this with you The tutorials and practicals, the reason they get confused with each other is that because sorry, tutorials and how to guides, they get confused with each other because they are both practical. So if we've got explanation stuff hiding in the tutorial, I would take it out of the tutorial, but I wouldn't put it in a how-to guide. I would put it. In explanation stuff. You know, in fact, I would put it in um the overview, the initial overview of testing, which was This one here.

Speaker 1: The introduction for it, maybe. But what would you suggest to do with this page, what would be one thing that we could do with this page that would start to make things feel a bit better

Speaker 2: So I don't know. But if it's are we trying to split it into like problem solution problem solution or something like this?

Speaker 1: I would rename it to how to write and run tests. That would be the first thing I I would do. Because now I've put a writing and running running tests is an unclear title. The title, Running and Writing Tests, allows lots of things to slip in there. It's quite easy to slip in stuff about about running tests. Whereas one of the things that we realize is that this is about how to write tests, how to run them, and and other people notice that. Let's change the title Give it a better title. And uh I'm not sure if you can see the um URL, but the URL, we should move it out of topics and into the how-to section. And once it's got the name, we can start making it live up to the name.

Speaker 1: So changing the names of things is often a really good trick to help you, not trick, but a good technique to help you onto the right path. And if somebody starts writing long-winded explanation in here, we say, well, no, this is a how-to guide. The explanation lives somewhere else. So I think that's um that 's worth doing with. Um so What if something in this page is actually explanation material and not how-to

Speaker 1: material? Should that prevent us from acting?

Speaker 6: Um since the have two assumes like knowledge or since you're doing something, I think it's safe to assume That the person like um uh I think you should link to an explanation or something like uh another acknowledgement, yeah.

Speaker 1: I I I agree. Um and yes, so let's have a look at Django 's um logging uh documentation okay so before in the bad old days there was one logging page in topics which mixed up explanation, reference, and how-to. And I think two years ago I split it into three documents. So we've got this logging overview, the introduction. This is where you come in. I'll tell you about the cast of characters. You know, this is this is I'll set the scene for you. I'll tell you about it. But I will tell you what to do. And I split out all the how-to stuff into

Speaker 1: this is, oh you want to use it. Here's your page for actually doing stuff with it. And each of these three pages, the reference, the overview, the explanation, and the how to point to the other But they're all about the same topic, but they talk about it in completely different ways. So the reference is just the facts These are the conditions, these are the values, this is what a configuration looks like. These are the loggers that are available, and so on. This is boring stuff. You'd look it up when you needed to know it The how-to guide is the stuff that you think, okay, yes, I'm going to improve my login

Speaker 1: configuration. You'll go here. But you might want to step back from it and have a look at your overview. And I think that is what I would like to do with our testing stuff We have got, we have, um, we're kind of running out of time now. You know, we could spend hours and hours on this, but I'm gonna leave you with homework. Okay. We have not one, not two. We've got four topic pages about testing. Uh my feeling when I see that is that people started tidying stuff up. They think, okay,

Speaker 1: there's a box marked testing. Let's throw some stuff about testing into it. And the first thing we can do to improve that, I said change the name. In other words, the first thing we can do is label one of the bloody boxes That will really help. And since this stuff this box seems to contain mostly how to stuff in there, let's rename it to how to. And then I would accept that as a pull request right now in Django. I think that would be a good pull request to rename this page and and the place where it is. That would be at least knowing what's in one of the boxes.

Speaker 1: I think that the third topic page is probably Or possibly mostly a reference page. I'm not sure yet. We have to look at it in more detail. I think this is because there were so this one is because there are so many boxes that people just thought, okay, let's call this one advanced because I can't work out how to put the other stuff in there. So we're gonna have to start wrapping up. What I want I'll not be on this uh where are we going to be where I can speak to people on the on the Discord, uh

Speaker 1: Sarah? In in this channel that was talking to you or a special one?

Speaker 2: Yes, you can talk to people in the there's like general and there's uh Django space. Yeah. General.

Speaker 1: Let's keep it for the people who are in this call. As homework. Is that what we can do then then? Okay. Alright, okay. So I'll hang around in there with you. And what I'd like you to do is to Start with this page, should we say, for the testing documentation? To find actions. And when I say actions, I mean something as simple as changing the title of a page And now you might get pushback from people, say, oh no, this is not a good enough pull request, but put my name on it.

Speaker 1: We'll force some of this stuff through using our you know, our charisma and status and so on, and we'll get changes happening. You've got some puzzles to solve, like that question about what what is a view, you know $20 prize for the person who comes up with the shortest best sentence that not explains it, but gives a sense of its meaning that will stick in the mind long enough for the tutorial to make sense Okay, I see a real opportunity for this testing documentation to be transformed, starting with the tutorial that leads us into the testing overview. There's brilliant material there already.

Speaker 1: And as long as a change you're going to make is going to be an improvement, I don't care how small it is. If it's a a a character improvement. That's worth a pull request. So don't try and make things perfect or solve all the problems. Or or you know, you might say, okay, this page needs to become a how-to guide, but there's a bunch of explanation stuff in the middle. Well, okay. That's fine, but naming it is still an improvement on the previous status of things. So that's worth doing Yeah, we don't don't believe in these people who say, oh yeah, it's it's not perfect yet. Well, it doesn't need to be in documentation.

Speaker 1: It's not it's not like code, you know. I mean the documentation is already not quite right, so we're making it better. Nothing's going to break. So does that sound like a fun thing we could do over a couple of weeks?

Speaker 2: I think that sounds excellent. Thank you so much, Daniela. I will uh stop the recording. Thank you.

Speaker 1: I I talked way more than I I wanted to, but I realized we just We we need to do stuff and and you need to go and read the about the taxis if you haven't done so already and think about it and Argue about it and tell me why you think it's wrong and so on. But uh you need to engage with those ideas. Um, but the most important thing to do is to see Something in there, oh yeah, I could improve that. And then we'll talk about doing it and we'll do it in tiny steps, but we'll get we'll we'll do that. Okay.