 Hi, everyone. Thanks for coming to hear me again, if that's again for you. I'll quickly tell you about me. I'm Daniele Prachida. I work for DIVIO. I'm a community manager at DIVIO. I'm a Django CMS developer and a core developer also of the Django project and a board member of the Django software foundation. There's my email address. You can find me as EvilDMP on IRC and GitHub and so on. So some people take quite seriously this idea that you should write your documentation first and then the code should follow. It's something that's not discussed or practised nearly as much as test-driven development. In fact, I don't actually know anyone who really does documentation-driven development or even talks about it. I don't want to spend too much time on this, but documentation-driven development is the idea that reverses the typical priority of code and documentation. You start with the documentation instead of the code, and instead of documenting the code, you code the documentation. It's rather like test-driven development in that it puts what should be the case before what is actually the case. It helps establish a shared and easily accessible higher-level overview of the work at hand. It provides a shared and easily accessible metric of success for the work, which is important. It encourages the contribution and engagement of non-programmers, and it binds the programming effort into a coherent narrative. The honest truth is that I don't know very much more than this about documentation-driven development, though I'm sure it's a valuable development practice that more people should adopt. In fact, what I want to talk about is not this exactly, but some other senses in which documentation drives development. I want to have a look at Django and the Django project and consider what documentation has meant for Django's development. The first thing we should say is, and it's not because this is a new observation, but simply because everybody seems to agree on it, is that Django's documentation is exemplary. I've not come across any other similar project, possibly any other project at all, with better documentation than Django. Perhaps my experience is just a bit limited, but I don't think anybody else seems to have come up with a project with better documentation than Django has. Well, what actually is so good about Django's documentation, first of all it's structured properly, so it's structured into a very clear division between tutorials, how-to's, reference material and topics, and I'll discuss the implications of that a bit later, but that structure matters a lot. Within the structure, it's very clear and consistent. It's comprehensive, it covers just about everything. All of it is held to very high standards, so you need to work as hard on documentation as on code if you want to get it accepted into Django itself. It exemplifies important values such as clarity, courtesy, friendliness. Finally, documentation in Django is a process rather than a product. Again, that's something else I want to talk about particularly later. All these are the things that actually make the documentation good as documentation, and the differences it makes, the effects it has, are important for the project. It makes Django easier for people to learn and adopt. It makes those people who do adopt Django into better programmers. It lowers the support burden on people who are supporting new programmers or programmers who are trying new things or need help, and it also makes the development of Django itself easier and faster. In other words, Django's documentation is very good for Django. Without any doubt, it has been part of what has improved Django over the years. Now we come to the main point of this talk, and that is that software is not the only thing that develops and grows and improves. Programmers and communities of programmers also develop and grow and improve, and it's programmers and communities of programmers that make the software grow and develop. What does documentation mean for the development of communities and programmers? Why does documentation manage matter to them? Let's think about the Django community. Django's community, like the software, is stable and mature and dependable. You know where you are with Django's community. The community is active, it's engaged, and it's remarkably united, given that it's so large and is used by so many different people in so many different ways and places. Like all communities, it has its difficulties sometimes, but there are very rarely in Django crises that afflict some other communities, and we don't see in Django these lingering ills that seem to blight some other communities. I think that one of the glues that has bound this community together is in fact Django's documentation. I think that when it comes to the development of the community that Django's documentation does four very important things. I said earlier that it represents the attitudes of the community, but it's stronger than that. Django's documentation or the care that Django's documentation takes is an implicit contract that it makes with its community. It's a commitment to standards of communication and information, and it treats documentation as an activity and not just as content. This last is, I think, the deepest of all these points, the most important, so I'm going to start with that one. Everybody learned programming who's a programmer. Have you ever had this experience of hesitating to ask for help with a programming question, perhaps on IRC on or somewhere online? Because you felt that the answer must be out there already if only you knew how to find it. Sorry, your hand's up because you had that experience. I thought it was a signal that I was misinterpreting. That would be interesting. Who has had this experience of hesitating to ask for help online because you felt the answer was probably already out there if only you knew how to find it or search for it or ask for it and you were a bit anxious that you might be invited by somebody who was a bit irritated to read the fucking manual by somebody who thought you were being lazy or stupid. I think most people have had that experience. You might be right to hesitate because people who already know things can be remarkably forgetful about how they learnt them or about what it was like not to know them. People are not always sympathetic and friendly to people who don't yet know the things that they do. To the extent that programmers are young men full of confidence, they're not always the most empathetic group of people in the world who are the ones who are most easily able to understand other people's position even if it was a position that they themselves held. Or perhaps you've asked a question and has anyone had this? You've asked a question and someone's replied with a link to this sarcastic website. Do you know this, sir? Let me google that for your website. You put your search into it and it does a sarcastic simulation of somebody searching for something on Google. I really hate... I did test that website. I really hate everything it stands for because what it stands for is putting people down when they have a question to ask. Thank you. It stands for putting people down who are asking for help in understanding something and it means telling them that the reason they don't understand the thing that they want to know is that they're too stupid or lazy to learn it. Insofar as information and documentation are content, it's possible to have to think and respond like that. The content is out there, especially in Django, if you're asking a question about Django on IRC or something, probably the answer is in the documentation. The temptation might be quite high for someone to say, let me google that for you because it's there. We know it's not quite so easy because we don't always know what we're looking for. But if you think of information and documentation just as content, you can say, well, the content's there. It's freely available to anybody with an internet connection. Go ahead, help yourself. If you can't find it, if you don't find it, that's your problem. Other people managed. If we think about information and documentation differently, if we think of them as processes or activities, then that kind of, let me google that for you, sarcastic response, is much less possible. And we do see that response much less in Django than I've seen in other programming communities. Our IRC channels and email lists are very friendly places, and the experts of the community who are there regard information and documentation as activities that they are engaging in, not as stuff that people should have read before wasting other people's time. So they consider that information is something that they do, documentation is something that they do, not something, some stuff that exists out there. So information in this model is regarded as a communicative transaction between agents. And information on this model demands that we respect values of clarity, is what I'm saying clear, intelligibility. Am I saying it in a way that the other person can make sense of it? Relevance is what I'm saying actually relevant to the problem that the person talking to me has. Comprehension, can the other person understand what I'm saying in answer to their question? Attention to the needs and abilities of the other party. Do I speak in the same way to a complete beginner who doesn't even know how to answer the question in the ideal way that I would answer to somebody who's very experienced? And affirmation of mutual understanding, have I checked that you have understood my answer to your question? So to the extent that we regard information as a communicative transaction between me and you, between me and the person I'm trying to help, I cannot pretend that telling them to read the fucking manual is informing them, that's not informing them, because it's missing out all of that. And sarcastically googling for them misses all of those points. So good documentation shows respect. And there's a default position that if someone doesn't understand the documentation, then the problem lies as much in the documentation, or in the documentation rather than with the person who struggled to understand it. It becomes an expression of those values. So Django's documentation sets standards and expectations and the tone for communication, especially with communication with the less expert users of Django. Its documentation is an assertion of values that are subsequently asserted across and reflected the whole Django community. And what I think this means is that within Django in this community, when I say Django actually I include a lot of Python too, because it's most obvious in Django, but you do see it in Python in ways that you don't see in other programming communities. We think of information as the activity of informing, something we do rather than as a collection of content. And this idea of information has had real meaningful beneficial consequences for people who use Python and Django. So I said earlier that Django's documentation has been good for Django, but I think it's much more than merely good. Django's documentation informs its community, and to inform something means literally to shape it, to inform, to press a shape into something. So Django's documentation has literally informed, shaped the Django community. It has determined how the community has developed, what sort of thing it has developed into, and it's one of the things that continues to shape and drive the development of Django. And that's the kind of development I'm speaking of when I'm speaking of documentation-driven development, because documentation is one of the things that determines the way Django is growing and developing. I want to take a little digression here. So the attitude towards documentation in Django has had a tangible difference that you can experience yourself, not just when you're thinking about it for writing talks and analysing it, but in an ordinary, everyday way. And it's brought to me quite forcefully sometimes, especially when I speak to people outside our cosy world of Django, and I have an interesting experience. If I tell people that I'm a member of the Django core development team, then if they know what Django is, then they're impressed, and they're like, oh, you're a member of the Django core development team, that's really cool. And then they say, well, and what do you work on? And I say documentation mainly, or I might tell them part of my job title is documentation manager. And other programmers from outside the Python Django community sometimes find it a little bit hard to hide their sudden disappointment, or even their embarrassment, embarrassment for me. So it's like, oh, documentation. It's like a moment ago they thought they were being introduced to Superman, and it turns out it's only Clark Kent after all. And sometimes you see a flick of an expression on their faces, and you think, is this a joke in bad taste that this person is admitting to this? And I swear that once or twice I've had the impression that somebody was about to say, but isn't that woman's job? So I'm really serious about this. It's something that I encounter in some funny ways. And it's honestly, as though I were admitting to having an unmanly personal habit, like crying or whining a lot, or writing a function when I should have written a class, or using the wrong kind of workflow on Git. And I mean, it's true that I do all of those things, especially the crying and whining. But to have people feel embarrassed for me and start to look desperately around the room for somebody more interesting to talk to, because I admitted to them that what I mainly do is write documentation tells you an awful lot about where it fits into some people's picture of the world. When I tell somebody from the Python or Django communities that my main role is in contributing to documentation, their reaction typically is, oh, cool. So there's a real cultural difference between these communities. I was surprised, I saw it in some of the literature from, I think some of our sponsors of this conference, that they were looking for ninjas and rock stars. And I'm really surprised to find that here. So what sort of attitudes would you expect people in programming communities to have towards documentation when so many of them think that they should aspire to be ninjas and rock stars? Where did this come from? Why do companies think they might benefit in some way from employing rock stars or ninjas? So ninjas are mainly famous for setting fire to buildings in the dead of night, and that's a very interesting metaphor in which to base your recruitment strategy. Or, you know, the notion of employing rock stars. The mind boggles, frankly. What's the defining characteristic of a rock star? You know, excessive behaviours, unreasonable demands, an expectation that maybe underage girls with self-esteem issues might be willing or should be willing to offer them sexual favours? The whole thing seems unbelievably mature and astounding when you see it coming out of not just a start-up being run by young men who themselves have barely stopped being teenage boys, but corporations. You think maybe airline pilots would be a more appropriate metaphor or surgeons or chefs or anything at all in which being disciplined, thoughtful and highly skilled and being able to collaborate with other people well to achieve good outcomes would be a better metaphor for excellent programmers, so we have to be ninjas and rock stars. You know, on one side arsonists, on the other, actual arsholes. So it's childish and immature. It does affect the community. It does affect the way people think. It does affect the way those parts of the industry where such attitudes are allowed to dominate, it affects the way all those things work and it makes them worse and it makes those companies and projects worse places to be. So I'm going to come out of my digression now back to black. So genuinely I think that Django's documentation has been part of what has helped Django avoid this kind of blight. It has informed, it has shaped the Django community into being a better place. It has developed it into better ways. And documentation has implications for programmers as individuals, as practitioners in similar ways. Developers develop. Which is to say that their programming skills develop, get better. And the question for many programmers is how do I develop? How do I become a better programmer? And it's a true but quite uninteresting observation that good Django documentation helps Django programmers write better code. But again I think the implications are wider than that. So, not just in Django but everywhere, documentation is an excellent way for newcomers to something to start contributing to it, to open source software especially. You don't need to be an expert in something to be able to identify something unclear or lacking in its documentation and to suggest a way to improve it. Writing documentation represents a really good and easy first step from being a user of something to being an active contributor to it. Especially in open source projects, documentation is almost always welcome. In fact in most projects it's not so much welcome as desperately needed. And you'll find that it's far easier to get documentation accepted into an open source project than it is to get code accepted into it. Simply because the documentation is more badly needed than a new feature is. And of course explaining something to someone else is just about the best possible way to explain it to oneself, to learn and understand it. So if part of a program is development is to contribute and understand more, documentation is an ideal way to do it. It will raise the contributors' understanding of the whole of it. And the Django project really does get all of this. It really does understand all of this. Django's documentation structure does an excellent job of guiding and encouraging new contributions and new contributors. In Django the clarity of the documentation structure makes it almost obvious how and what to write for a particular section just as well-written code does. And this works very well for maybe huge new or large new contributions, maybe an entire new section of the tutorial, or for tiny ones such as an aspect of some key function that deserves more explanation. So it invites the person in the new contributor and shows them where to go and how to do what they want to do. Contributions to Django's documentation are taken very seriously and they're held to the higher standards. Contributions to documentation and the contributors who make them receive as much support and encouragement and engagement as those who are contributing code. In many other projects documentation will be accepted just because it's documentation, and the quality of it is not always an issue. In Django documentation goes through the same ringer that code goes through. You'll find if you're submitting documentation to Django that there's somebody saying, well, no, you need to change this. Who will send it back to you and be prepared to sit there and go through a long review process of many cycles to help you get the documentation just right for Django. So you, as a documentation contributor, will be taken as seriously as if you were contributing some key code. It won't be accepted just because it is documentation. The other thing is that these contributions are valued and recognized by the Django project and the Django community. So everybody who's on the Django core team has made substantial contributions to Django. My contributions have pretty much all been documentation contributions, not code. So there are these three things that Django gets very right. The documentation guides its contributors, it's taken seriously, contributors are valued highly, and they're important because of this fact that most people say they recognize, and then in the end few people act as though they really believe it, that documenting code is the best possible way to understand it. Documenting code will make you a programmer who understands more things and understands them more deeply, and Django encourages developers to write documentation. All of this means that Django not only gets more and better contributions to its documentation than other projects do, it's also very successful in advancing the skills of those who contribute to it. If you want to learn how to contribute to open source software in Python, there is probably no single better place to start than by looking at the Django documentation and thinking could you make a contribution there, because you will get a first-class introduction in how to contribute to a major project. Your work will be checked by somebody who is extremely thorough about it. You will be guided and engaged with it at every step of the way. So if you want to start being an active contributor to open source software in Python, probably there isn't anywhere better to do it. So this is what I mean when I say that Django does documentation-driven development. I mean that through its documentation it develops, it advances, it improves both its community and its developers. So that's the lesson from the Django project. What can you do? What can your project do to reap some of the same rewards from its documentation? Well, I don't think it's something that can be accomplished overnight. Much of this is to do with attitudes, and attitudes are very hard things to change. At the same time, the actual steps you can take are easy, and if you keep taking them and taking them in the right direction, eventually, not at first, but in time, attitudes will follow those steps. So some practical things, just very briefly. I'd be happy to talk about this more. One is to structure documentation correctly. So if you have a look at the first page of the Django documentation, it explains this. It doesn't get those four categories mixed up, tutorials, how-to's, reference or topics. And most documentation does. A tutorial takes somebody by the hand from not necessarily zero, but from a known low starting point to a position of success. So here's one task. It might be just to set up a Django project. We'll get you to the end of it. If you follow these steps, you're pretty much guaranteed success at the end. That's completely different from a how-to, which is like a recipe in a cookbook, which requires that you understand at least the basics of how to use the kitchen and the tools. Reference material shouldn't need to tell anybody how to do anything. It just describes what is there. And topics are discursive material that they describe stuff. They don't tell you how to do something. They don't list the bits and pieces of an API. They don't need you step-by-step through anything. But they will give you a higher level overview and understanding of it. And I'll happily talk about that some more if anyone's interested. Make your documentation policies as rigorous as your code policies. Don't be afraid to bat documentation back at its contributors. Just because somebody has submitted documentation, don't accept it. Take it seriously, as seriously as you take code, and ask for it to be improved if it needs to be improved. You wouldn't accept some sub-standard code, so don't do the same for documentation. People appreciate being taken seriously. Sub-standard code can harm your applications, but sub-standard documentation can harm your community, which is worse. Document your documentation. Make sure it's clear what its policies are, what you want from each section of it, what you expect of the contributors to it. Value your documentation contributors, whether they're internal or external. Recognise them publicly. Make them a core developer of your project if they've contributed enough. Value the activities of documentation and information, and set aside time for them. If you or your project or your company are really serious about this, there are some real commitments that you can make. You can make being a documentation manager part of someone's role. You could pay someone to have that responsibility. You can spend money and time on documentation. All of this doing that will certainly help achieve the things on this page. Right here in the Python... Who uses Read the Docs, by the way? I should say, does anybody here not use Read the Docs? Right here in the Python community, we have one of the most important and valuable resources anywhere in the whole of the open source world of programming. Read the Docs. It's free, it works brilliantly, it runs on Python, and it's cruelly, scandalously underfunded. So it's kept alive by Eric Hulsher in the middle of the night, answering calls from his pager for almost no money. There have been times in the past where he was losing money to keep Read the Docs afloat. The company I work for, Divio, we're one of the sponsors of the Read the Docs website. So if you care about this kind of thing, then a small amount of money from your company would go an extremely long way. Alongside the Read the Docs, part of the same family of activities, there's the Write the Docs conference in Europe and the US. Absolutely brilliant, really interesting conference. Really interesting to notice that in the Write the Docs conference, about half the speakers were technical writers, and most of the developers who were at the conference were from the Python Django communities. Again, reflecting the attitude, the esteem in which documentation is held in our communities. They also have meet-ups to have a look at Write the Docs.org. So if I would like you to take away one thing from the last 35 minutes or so, it's this, that information and documentation are activities that we engage in, and they are not stuff that we produce or consume. Thank you. Okay, we have time for some questions. Thank you for the talk, very inspiring, but I have a more pragmatic question. I don't use Django that much. Actually, I almost don't use it, but you probably have a lot of documentation, right? So how do you keep the documentation in sync with the code? For example, I've heard people saying that Doc strings are doomed to fail because they will always be synchronised. So how do you do it? Partly by making documentation as important as the code. So if you changed a part of the code and it affected another part of the code, you wouldn't change only one part and then leave the other part, you know, something that used that API. You wouldn't leave that in a broken state, would you? So in the same way, why would you want to leave the documentation in a broken state? And the developers of Django will just send it back, say, you know, you've changed the code, but what about the documentation? Just like you wouldn't, if it made tests fail, you would... Is it always obvious that if a developer changes a bit of code that he has to change the documentation? No, nothing is obvious, but if you have a whole community who spend a lot of time thinking about the documentation, it might not be obvious, but at least there are a lot of people who are taking an interest in it and it's much harder for it to slip through the net. So, you know, I would never pretend that any of these things are easy, but when you've got a lot of people who care about something, it certainly helps. Yeah, of course. One question over there. It's not a question, it's just an answer following that Danielle. Is there actually a rule in Django Project to fix, to get the tests going and to fix the documentation with the patch, so otherwise it will be refused? Thank you. Another question? Kind of tying into the previous question as well. Do you think doc tests are a good tool to keep the docs in sync with the code? Can you explain what you mean by doc tests, please? Which is a thing in Python or also a support in PyTest where it can write examples in a doc string and it tests those examples. And I'm wondering if you know how well it works out in practice. No, I've never used that. And I think it's really important for documentation to be curated by humans. So, when you go to... This is the kind of... Reference is what programmers like writing. They love writing reference materials, okay, because they're describing, oh, here's the machine I made, here are all its parts, and you can put all of the descriptions of that machinery into the machinery and have it automatically generated. But it's only useful for people who already have a general understanding of what the thing is. It's not going to be any use for anybody who needs a description or a kind of topic description who needs to know how to use it, a kind of general recipe, and certainly won't help a beginner who's looking for a tutorial. So, I guess they may have some place somewhere, but for the vast... Paul Ruland over there is shaking his head. He says they have no function anyway. I don't know about that. But I know that for the most of the documentation, you're writing for humans, so that's a good question. Thank you. I have a question over there. Have you heard of Jupiter? Sorry, that's just a joke. The question is with developers who maybe don't know English so well, just say their level is maybe B2 or something like this, how do you... Do you have anything which can help them? Because I found a lot of people would rather just not write documentation in those cases. Really good code, but... Yes. Well, firstly, even if people don't speak very good English, they probably learnt it before they learnt Python, even if they're not a native speaker. But secondly, they can be some of the most useful contributors to documentation, because if you're writing for somebody whose first language is not English, then you'd better write your English in ways that can be understood really well, and those people will be the best people to tell you that your documentation is not clear. Your documentation has to be clear enough for those people, and if they can contribute to it, they may not be the greatest stylists, but they will have some of the simplest language and give you directions for the way that language needs to go in order to be comprehensible. So this is understanding the other people who are reading your documentation as part of the process too. It's not just a question of, you know, here's the documentation. Understand it if you can. There's this relationship between the two. So they're an important part of that. Thanks very much. It's a good talk. I've got one statement firstly. I really like the Django Girls documentation because it kind of starts at, like, ground zero. There's no presumptions about anything that the users should or shouldn't have. Also, I've really appreciated the Plane documentation has improved massively over the last few years. But what I've noticed before working for the last 10 years with Python is when you deal with people outside of the Python community, you often felt to be a lesser developer when you say you do document because you're not spending your time, say, programming. I was wondering, do you have any advice, because I kind of feel like it has to be a top-down thing in these organisations, but do you have, like, one bit of advice how you can kind of combat that? Combat, you know, if you're combat, maybe ninjas should be sent into combat. Attitudes are the hardest thing to change. Python and Django are successful partly because of their documentation. They're the reasons that so many people are coming in. And if we can keep people coming in, then we will be changing the culture just by having people part of our community and inculcating them in the ways of our community. Other than that, if somebody gives you a look-in horror because you write documentation at a party or a meet-up, you just have to live with it. What can you do? Doesn't Django have documentation in languages other than English as well? It does. Yes, I think the documentation is translated into French completely, and I think somebody is translating it into Spanish at the moment. I was just wondering... Yeah. Translation is a hard job. I was just wondering about that because of the previous comments about languages and stuff. Actually, that's the person who asked me about non-native English speakers. Yeah. Another option is to translate all the documentation into another language. That really is a labour of love. Nobody got rich or famous by translating open-source documentation into another language. Okay, so do we have any more questions? Okay. Yeah, thank you for your great talk. And you really speak to my heart regarding documentation. I think it's very, very important and should be treated as a first-class citizen among ourselves. So that's more like feedback than a question. Thanks for your talk. Thank you very much. Thank you. Thank you very much for your time. If you'd like to talk to me about any of this, come and find me. I'll be very happy to talk about documentation and give practical suggestions about it. Just one very last thing if I may very briefly. I'm not a Django wagtail or Django Oscar developer, but if you are, I've got some quite exciting news for you. So come and find me afterwards and talk to me. Thanks once again for listening to me.