Documentation-driven development
This is a modal window.
The media could not be loaded, either because the server or network failed or because the format is not supported.
Formal Metadata
| Title |
| |
| Title of Series | ||
| Part Number | 71 | |
| Number of Parts | 169 | |
| Author | ||
| License | CC Attribution - NonCommercial - ShareAlike 3.0 Unported: You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal and non-commercial purpose as long as the work is attributed to the author in the manner specified by the author or licensor and the work or content is shared also in adapted form only under the conditions of this | |
| Identifiers | 10.5446/21121 (DOI) | |
| Publisher | ||
| Release Date | ||
| Language |
Content Metadata
| Subject Area | ||
| Genre | ||
| Abstract |
|
EuroPython 201671 / 169
1
5
6
7
10
11
12
13
18
20
24
26
29
30
31
32
33
36
39
41
44
48
51
52
53
59
60
62
68
69
71
79
82
83
84
85
90
91
98
99
101
102
106
110
113
114
115
118
122
123
124
125
132
133
135
136
137
140
143
144
145
147
148
149
151
153
154
155
156
158
162
163
166
167
169
00:00
Red HatDemonMetropolitan area networkSoftwareData structureCanadian Mathematical SocietyData managementSoftware developerCore dumpProjective planeWhiteboardEmailSystem callAddress spaceRight angleSoftware testingCodeTest-driven developmentXMLLecture/ConferenceJSONComputer animation
01:03
CodeSoftware testingLevel (video gaming)Software developerMultiplication signCodeCASE <Informatik>QuicksortMetric systemTest-driven developmentLecture/ConferenceJSONXML
01:50
CodeSoftware testingLevel (video gaming)Metric systemKeyboard shortcutComputer programmingSoftware developerProjective planeLecture/ConferenceJSONXML
02:32
Software developerState observerProjective planeMusical ensembleBitComputer animationLecture/Conference
03:13
Data structureCovering spaceStandard deviationAgreeablenessProduct (business)Process (computing)GenderData structureBitCovering spaceDivision (mathematics)Lecture/ConferenceJSONXML
03:57
CodeStandard deviationProcess (computing)Product (business)Goodness of fitAgreeablenessDifferent (Kate Ryan album)Lecture/Conference
04:45
Different (Kate Ryan album)Sound effectProgrammer (hardware)Projective planeSoftware developerOnline helpWordJSON
05:23
MereologySoftwareProgrammer (hardware)Software developerPoint (geometry)Arithmetic meanData managementXMLComputer animationLecture/Conference
06:19
Different (Kate Ryan album)Software developerXMLComputer animationLecture/Conference
07:09
Design by contractCommitment schemeTelecommunicationInformationStandard deviation3 (number)GenderStandard deviationSoftware developerSocial classDesign by contractContent (media)Commitment schemeTelecommunicationPoint (geometry)Euler anglesInformationMeeting/Interview
08:09
Programmer (hardware)Online helpComputer programmingBitComputer animation
09:10
Right angleProgrammer (hardware)Position operatorExtension (kinesiology)Group action1 (number)Confidence intervalLecture/Conference
10:00
Object (grammar)Function (mathematics)WebsiteLink (knot theory)SimulationGoogolLecture/ConferenceJSONXMLUML
10:38
Object (grammar)Function (mathematics)Content (media)Product (business)InformationOnline helpInformationContent (media)Lecture/ConferenceComputer animation
11:13
InformationContent (media)GenderWeightGoogolConnected spaceOnline helpInternetworkingLecture/Conference
12:00
Content (media)Product (business)InformationProcess (computing)InformationProcess (computing)Dependent and independent variablesComputer programmingEmailExpert systemElectronic mailing listStaff (military)Multiplication signComputer animationLecture/ConferenceMeeting/Interview
12:53
Database transactionInformationWechselseitige InformationInformationEndliche ModelltheorieDatabase transactionTelecommunicationJSON
13:45
InformationDatabase transactionWechselseitige InformationWechselseitige InformationExtension (kinesiology)InformationCommutatorDatabase transactionLecture/ConferenceJSON
14:28
Point (geometry)Goodness of fitDefault (computer science)Position operatorExpressionSet (mathematics)Expected valueStandard deviationLecture/ConferenceComputer animation
15:09
TelecommunicationExpert systemStandard deviationExpected valueMessage passingInformationComputer programmingContent (media)Lecture/Conference
15:59
InformationGenderReal numberSoftware developerGoodness of fitShape (magazine)TriangleQuicksortComputer animation
16:50
Dean numberSoftware developerSpeech synthesisEuler anglesHuman migrationDifferent (Kate Ryan album)GenderLecture/ConferenceXMLUML
17:45
Software developerCore dumpProcess (computing)MereologyBitDocument management systemProgrammer (hardware)Lecture/Conference
18:28
Moment (mathematics)ExpressionProcess (computing)Lecture/Conference
19:07
Functional (mathematics)Social classDifferent (Kate Ryan album)WritingXMLUMLLecture/Conference
20:11
QuicksortEuler anglesExpected valueComputer programmingBuildingStrategy gameXMLComputer animationLecture/Conference
20:59
Expected valueCharacteristic polynomialLecture/Conference
21:38
Programmer (hardware)QuicksortComputer programmingEuler anglesMereologyProjective planeMedical imaging
22:22
MereologyShape (magazine)Similarity (geometry)Software developerProgrammer (hardware)Lecture/ConferenceComputer animation
22:58
CodeComputer programmingMereologyState observerProgrammer (hardware)Open sourceSoftwareGoodness of fitLecture/Conference
23:45
Level (video gaming)Open sourceCodeProjective planeSource codeExpert system
24:46
MereologySoftware developerProgrammer (hardware)Projective planeData structureGenderProcess (computing)Lecture/ConferenceComputer animation
25:24
LogicSheaf (mathematics)1 (number)Functional (mathematics)CodeData structureLecture/Conference
26:08
Standard deviationStandard deviationCodeProcess (computing)Cycle (graph theory)GenderProjective planeRing (mathematics)Computer animationLecture/Conference
27:10
CodeProjective planeCore dumpComputer animation
27:51
CodeElectronic program guideGenderRight angleSoftware developerCodeProgrammer (hardware)Lecture/ConferenceComputer animation
28:52
Projective planeSoftwareOpen sourceSocial classComputer animation
29:28
Projective planeOpen sourceSoftwareSoftware developerLecture/ConferenceComputer animation
30:10
Projective planeSoftware developerEuler anglesRight angleMultiplication signDirection (geometry)Lecture/Conference
31:04
CAN busData structureCodeInformationWeb pageCategory of beingProjective planeMixed realityPoint (geometry)Position operatorTask (computing)Data structureJSON
31:43
CAN busData structureCodeInformationLecture/ConferenceJSON
32:20
Level (video gaming)CodeBitElectronic mailing listStapeldateiCartesian coordinate systemLecture/Conference
33:22
Data structureCodeInformationCAN busMereologyDocument management systemSheaf (mathematics)Finite-state machineSet (mathematics)InformationMultiplication signProjective planeCommitment schemeMereologyCore dumpSoftware developerJSON
34:09
Multiplication signDependent and independent variablesWeb pageRight angleOpen sourceLecture/ConferenceJSONXMLUML
34:48
Computer programmingMultiplication signWebsiteLecture/Conference
35:25
FamilyMereologyRight angleSoftware developerJSONXMLUMLLecture/Conference
36:02
Product (business)InformationEuler anglesInformationComputer animation
36:43
Multiplication signCoefficient of determinationSynchronizationMereologyRight angleCodeComputer animation
37:33
Software testingCodeBitSoftware developerMultiplication signMereologyMathematicsState of matterWeightMeeting/Interview
38:43
Projective planeSynchronizationSoftware testingRule of inferenceIntegrated development environmentGenderPatch (Unix)Code
39:27
CAN busData structureCodeInformationSoftware testingComputer programmingRight angleString (computer science)Programmer (hardware)Descriptive statisticsWritingVirtual machineMaterialization (paranormal)Lecture/ConferenceJSON
40:14
Online helpDisk read-and-write headFunctional (mathematics)Descriptive statisticsMeeting/Interview
40:53
Level (video gaming)Software developerDecision theoryCASE <Informatik>Code
41:30
MereologyWeightFormal languageOrder (biology)Data structureWritingDirection (geometry)Process (computing)
42:47
BitSoftware developerComputer programmingStatement (computer science)Multiplication signSelf-organization
43:36
MereologyEuler anglesMathematicsLecture/ConferenceMeeting/Interview
44:17
Formal languageMoment (mathematics)Sound effectComputer configurationTranslation (relic)Open sourceProcess (computing)Wage labourGroup actionLecture/ConferenceMeeting/Interview
45:12
Social classSound effectMultiplication signFeedback
45:48
DemonSoftware developerLecture/ConferenceXML
Transcript: English(auto-generated)
00:01
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 Prochida. 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
00:27
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
00:53
and then the code should follow. And it's something that's not discussed or practiced nearly as much as test-driven development.
01:02
In fact, I don't actually know anyone who really does documentation-driven development or even talks about it. And 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.
01:20
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.
01:41
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,
02:01
and it kind of binds the programming effort into a coherent narrative. And the honest truth is that I don't know very much more than this about documentation-driven development. I'm sure it's a valuable development practice that more people should adopt. But in fact, what I want to talk about is not this exactly,
02:23
but some other senses in which documentation drives development. So I want to have a look at Django and the Django project and consider what documentation has meant for Django's development.
02:44
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, and I have not come across any other similar project,
03:01
possibly any other project at all, with better documentation than Django. And 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?
03:27
First of all, it's structured properly, so it's structured into a very clear division between tutorials, how-tos, reference material, and topics, and I'll discuss the implications of that a bit later,
03:41
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
04:05
if you want to get it accepted into Django itself. It exemplifies important values such as clarity, courtesy, friendliness,
04:21
and finally, documentation in Django is a process rather than a product, and again, that's something else I want to talk about particularly later. So all these are the things that actually make the documentation
04:43
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.
05:05
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. So in other words, Django's documentation is very good for Django.
05:23
Without any doubt, it has been part of what has improved Django over the years. And 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.
05:47
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.
06:04
So what does documentation mean for the development of communities and programmers? Why does documentation matter to them? Well, let's think about the Django community. Django's community, like the software, is stable and mature and dependable.
06:25
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,
06:44
but there are very rarely in Django crises that afflict some other communities, and they're very rarely in Django. We don't see in Django these lingering ills that seem to blight some other communities. And I think that one of the glues that has bound this community together is in fact Django's documentation.
07:08
I think that when it comes to the development of the community that Django's documentation does four very important things.
07:22
I said earlier that it represents the attitudes of the community, but it's stronger than that. The care that Django's documentation takes is an implicit contract that it makes with its community.
07:44
It's a commitment to standards of communication and information, and it treats documentation as an activity and not just as content. And this last is, I think, the deepest of all these points, the most important.
08:02
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,
08:21
perhaps on IRC or somewhere online, because you felt that the answer must be out there already if only you knew how to find it or... Sorry, your hand's up because you're... Oh, because you had that experience. Yes, okay, good, yeah, sorry. I thought it was a signal that I was misinterpreting.
08:43
So, yeah, 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,
09:07
by somebody who thought you were being lazy or stupid? Well, I think most people have had that experience. And you might be right to hesitate, because people who already know things can be remarkably forgetful about how they learnt them
09:23
or about what it was like not to know them. So people are not always sympathetic and friendly to people who don't yet know the things that they do. And to the extent that programmers are young men full of confidence,
09:46
they're not always the most empathetic group of people in the world and the ones who are most easily able to understand other people's position, even if it was a position that they themselves held.
10:02
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? The Let Me Google That For You website? You put your search into it, and it does a sarcastic simulation of somebody searching for something on Google.
10:26
So I really hate, I detest 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.
10:43
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.
11:03
So insofar as information and documentation are content, it's possible to have to think and respond like that. You see, the content is out there,
11:21
especially in Django, where the content, if you're asking a question about Django on IRC or something, probably the answer is in the documentation. So the temptation might be quite high for someone to say, well, let me Google that for you, because it's there. I mean, we know it's not quite so easy, because we don't always know what we're looking for.
11:41
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,
12:03
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
12:22
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.
12:45
So they consider that information is something that they do. Documentation is something that they do, not some stuff that exists out there. So information in this model is regarded as
13:03
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?
13:21
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?
13:40
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?
14:05
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.
14:25
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.
14:44
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.
15:02
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
15:22
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,
15:41
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
16:03
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,
16:20
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,
16:42
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
17:02
that determines the way Django is growing and developing. I want to take a little digression here. So the attitude towards documentation in Django
17:22
has had a tangible difference that you can experience yourself, not just when you're thinking about it for writing talks and analyzing it, but in an ordinary, everyday way. And it's brought to me quite forcefully sometimes, especially when I speak to people outside our cozy world of Django.
17:42
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, they'll be impressed, and they'll be 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?
18:02
And I say documentation mainly. Or I might tell them, you know, 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
18:22
or even their embarrassment. Embarrassment for me. It's like, oh, documentation. It's like, you know, a moment ago they thought they were being introduced to Superman. It turns out it's only Clark Kent after all.
18:42
And sometimes you see a kind of 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.
19:01
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, you know, crying or whining a lot or writing a function when I should have written a class
19:21
or using the wrong kind of workflow on Git. 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,
19:45
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,
20:00
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,
20:22
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?
20:41
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 the notion of employing rock stars, the mind boggles, frankly.
21:02
What's the defining characteristic of a rock star? You know, excessive behaviors, unreasonable demands, an expectation that maybe underage girls with self-esteem issues might be willing or should be willing to offer them sexual favors. The whole thing seems unbelievably mature
21:20
and astounding when you see it coming out of not just a startup 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
21:45
and being able to collaborate with other people well to achieve good outcomes would be a better metaphor for excellent programmers. But no, we have to be ninjas and rock stars. You know, on one side, arsonists, on the other, actual arseholes. So it's childish and immature.
22:02
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.
22:23
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.
22:43
It has developed it into better ways. And documentation has implications for programmers as individuals, as practitioners in similar ways. Developers develop.
23:02
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.
23:25
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
23:42
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
24:04
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.
24:25
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 the new feature is.
24:40
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 programmer's development is to contribute and understand more, documentation is an ideal way to do it.
25:02
It will raise the contributor's 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 document, I talked earlier about structure, Django's documentation structure does an excellent job
25:24
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.
25:42
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,
26:02
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 highest standards. Contributions to documentation and the contributors who make them receive as much support and encouragement and engagement
26:24
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.
26:41
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, we 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
27:04
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.
27:26
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.
27:45
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.
28:07
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
28:22
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,
28:42
and Django encourages developers to write documentation. And 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
29:03
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
29:21
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,
29:41
you will be guided and engaged with 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.
30:03
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.
30:22
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, and much of this is to do with attitudes, and attitudes are very hard things to change.
30:43
At the same time, there are some, the actual steps you can take are easy, and if you keep taking them and keep taking them in the right direction, eventually, not at first but in time, attitudes will follow those steps.
31:01
So some practical things, just very briefly, I mean 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-tos, reference or topics,
31:22
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.
31:40
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.
32:03
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.
32:20
They don't tell you how to do something. They don't list the bits and pieces of an API. They don't lead 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,
32:43
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's submitted documentation, don't accept it. Take it seriously, as seriously as you take code, and ask for it to be improved,
33:02
if it needs to be improved. You wouldn't accept some substandard code, so don't do the same for documentation. People appreciate being taken seriously. Substandard code can harm your applications, but substandard documentation can harm your community, which is worse.
33:21
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. Recognize them publicly, make them a core developer of your project,
33:42
if they've contributed enough. Value the activities of documentation and information and set aside time for them. And if you or your project or your company are really serious about this, there are some commitments that you can,
34:01
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. And all of this, doing that will certainly help
34:22
achieve the things on this page. Right here in the Python, who uses readthedocs, by the way? I should say, does anybody here not use readthedocs? Okay, there you are. Right here in the Python community,
34:41
we have one of the most important and valuable resources anywhere in the whole of the open source world of programming, readthedocs. It's free, it works brilliantly, it runs on Python, and it's cruelly, scandalously underfunded.
35:02
So it's kept alive by Eric Holscher 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 readthedocs afloat. The company I work for, Devio,
35:21
we're one of the sponsors of the readthedocs websites, 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 readthedocs, part of the same family of activities, there's the writethedocs conference in Europe and the US.
35:40
Absolutely brilliant, really interesting conference, really interesting to notice that in the writethedocs conference, about half the speakers were technical writers, and most of the developers who were at the conference were from the Python Django communities.
36:03
Again, reflecting the attitude, the esteem in which documentation is held in our communities. And they also have meetups, have a look at writethedocs.org. So, if I would like you to take away one thing
36:20
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.
36:55
Okay, we have time for some questions.
37:06
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
37:23
in sync with the code? For example, I've heard people saying that docstrings are doomed to fail because they will always desynchronize, so how do you do it? Partly by making documentation as important as the code.
37:40
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, some thing 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?
38:01
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?
38:21
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 will 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.
38:43
One question over there. This other question is just an answer following Danielle. It's actually a rule in Django project to get the tests going and to fix the documentation
39:03
with the patch, so otherwise it will be refused. Thank you. You had another question? Kind of tying into the previous question as well, do you think doc tests are a good tool
39:22
to keep the docs in sync with the code? Can you explain what you mean by doc tests, please? There's this thing in Python, or also support in pytest, where it can write examples in a doc string and it tests those examples, and I'm wondering if you know
39:40
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.
40:00
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.
40:22
It's not gonna 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,
40:40
Paul Ruhland 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 a human being needs to write it. Thank you. Other question over there?
41:03
Have you heard of Jupiter? I'm sorry, that's just a joke. Sorry? 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,
41:21
because I found a lot of people would rather just not write documentation in those cases. They might write really good code, but yeah. Well, firstly, even if people don't speak very good English, they probably learnt it before they learnt Python,
41:40
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,
42:01
and those people will be the best people to tell you that your documentation's 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
42:21
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,
42:41
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 user should or shouldn't have.
43:02
Also, I've really appreciated the Plone 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.
43:25
I was wondering, do you have any advice, because I kind of feel like it has to be a top-down thing in these organizations, but do you have, like, one bit of advice how you can kind of combat that? Combat? You know, if you combat, maybe ninjas should be sent into combat.
43:42
Attitudes are the hardest thing to change. Python and Django are successful partly because of their documentation. It's one of 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
44:01
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 meetup, you just have to live with it. What can you do? Doesn't Django have documentation in languages other than English as well?
44:22
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...
44:40
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.
45:01
That really is a labor of love. Nobody got rich or famous by translating open source documentation into another language. Do we have any more questions?
45:23
Thank you for your great talk. 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. That's more like feedback than a question. Thanks for your talk. Thank you very much.
45:40
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.
46:01
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.