Documentation-driven development


Formal Metadata

Documentation-driven development
Title of Series
Part Number
Number of Parts
Procida, Daniele
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 license.
Release Date

Content Metadata

Subject Area
Daniele Procida - Documentation-driven development One secret of Django's success is the quality of its documentation. As well as being key to the quality of the code itself, it has helped drive the development of Django as a community project, and even the professional development of programmers who adopt Django. I'll discuss how Django has achieved it, and how any project can easily win the same benefits. ----- Part of my job title is Documentation Manager . When I explain this to a programmer outside the Python/Django community, the reaction can be anything from bewilderment to a kind of mild horror. When I mention it to a Python/Django programmer, the response is usually: Oh, cool . In fact, one secret of Django's success is the quality of its documentation, and everyone who uses Django is quick to note this. The returns on Django's investment have been substantial, but some of them are also surprising. The documentation has clearly been key to the quality of the code itself , but also (less obviously) to the development of Django as a community project , and even the professional development of programmers who adopt Django. I'll discuss how Django has achieved it, and how any project can easily win the same benefits.
Metropolitan area network Email Demon Red Hat Code Software developer Projective plane System call Computer animation Software Canadian Mathematical Society Right angle Software testing Data structure Whiteboard Data management Address space
Computer animation Code Personal digital assistant Multiplication sign Software developer Code Software testing Energy level Quicksort
Computer animation Computer programming Software developer Keyboard shortcut Code Software testing Energy level Metric tensor
State observer Musical ensemble Computer animation Software developer Projective plane Bit
Covering space Standard deviation Product (category theory) Computer animation Agreeableness Gender Covering space Division (mathematics) Bit Process (computing) Data structure Data structure
Standard deviation Goodness of fit Product (category theory) Process (computing) Lecture/Conference Code Agreeableness Subtraction
Programmer (hardware) Word Computer animation Software developer Projective plane Sound effect Online help
Point (geometry) Programmer (hardware) Arithmetic mean Computer animation Software Software developer Mereology Data management
Computer animation Subtraction
Standard deviation Standard deviation Information Euler angles Software developer Gender Content (media) Design by contract Computer animation Commitment scheme Telecommunication Telecommunication Design by contract Commitment scheme Information
Point (geometry) Standard deviation Programmer (hardware) Computer animation Telecommunication Computer programming Design by contract Online help Information Commitment scheme Social class
Computer animation Lecture/Conference Bit Online help Right angle
Programmer (hardware) Confidence interval Linker (computing) 1 (number) Website Extension (kinesiology) Position operator Local Group
Simulation Computer animation Function (mathematics) Object (grammar) Online help
Product (category theory) Content (media) Computer animation Information Object (grammar) Function (mathematics) Gender Content (media) Information Weight
Product (category theory) Content (media) Computer animation Information Internetworking Dependent and independent variables Information Process (computing) Connected space
Database transaction Email Database transaction Computer animation Information Multiplication sign Scientific modelling Telecommunication Expert system Staff (military) Information Mutual information
Database transaction Database transaction Computer animation Commutator Information Information Extension (kinesiology) Mutual information
Point (geometry) Default (computer science) Computer animation Expression Set (mathematics) Position operator
Expected value Standard deviation Message passing Information Telecommunication Computer programming Expert system Content (media)
Goodness of fit Computer animation Information Real number Gender Software developer Triangle Shape (magazine) Quicksort
Human migration Computer animation Euler angles Software developer Gender Speech synthesis Subtraction Dean number
Programmer (hardware) Document management system Process (computing) Software developer Core dump Moment (mathematics) Bit
Process (computing) Computer animation Expression
Functional (mathematics) Subtraction Writing
Expected value Building Computer animation Strategy game Euler angles Computer programming Quicksort
Expected value Lecture/Conference Characteristic polynomial
Medical imaging Meeting/Interview Euler angles Computer programming Projective plane Quicksort Mereology
Programmer (hardware) Computer animation Software developer Similarity (geometry) Shape (magazine) Mereology
Programmer (hardware) State observer Computer animation Open source Code Computer programming Projective plane Source code Expert system Energy level Mereology
Programmer (hardware) Process (computing) Software developer Gender Projective plane Data structure Mereology
Standard deviation Standard deviation Computer animation Code Logic Sheaf (mathematics) 1 (number) Data structure Functional (mathematics)
Process (computing) Code Gender Projective plane Ring (mathematics) Cycle (graph theory)
Code Projective plane Core dump
Programmer (hardware) Computer animation Code Gender Software developer Electronic program guide Code Right angle
Software Open source Projective plane
Open source Software developer Projective plane
Euler angles Software developer Multiplication sign Direction (geometry) Projective plane
Point (geometry) Web page Category of being Computer animation Mixed reality Projective plane Code Information Data structure Position operator Task (computing)
Batch processing Computer animation Code Electronic mailing list Code Energy level Bit Information Data structure
Information Code Multiplication sign Projective plane Sheaf (mathematics) Code Mereology Set (mathematics) Cartesian coordinate system Mereology Document management system Computer animation Commitment scheme Finite-state machine Information Data structure
Web page Computer animation Open source Meeting/Interview Multiplication sign Dependent and independent variables Right angle
Computer programming Multiplication sign Website
Computer animation Software developer Right angle Mereology Family
Product (category theory) Computer animation Information Meeting/Interview Euler angles Information
Hidden surface determination Computer animation Code Synchronization Right angle Mereology
Code State of matter Software developer Multiplication sign Gender Patch (Unix) Projective plane Bit Mereology Weight Rule of inference Mathematics Integrated development environment Software testing
Computer animation Computer programming Materialization (paranormal) Virtual machine Code Software testing Right angle Information Data structure Descriptive statistics
Personal digital assistant Code Decision theory Software developer Energy level Disk read-and-write head Functional (mathematics) Descriptive statistics
Process (computing) Direction (geometry) Software developer Multiplication sign Mereology Weight Formal language Computer programming Order (biology) Statement (computer science) Self-organization Data structure Writing
Mathematics Euler angles Mereology Formal language
Group action Process (computing) Wage labour Open source Lecture/Conference Computer configuration Moment (mathematics) Sound effect Formal language
Multiplication sign Software developer Sound effect Social class
Demon Computer animation
and the high everyone thanks for
going to me again if that's again for you and creatively about me I am Daniela structure I uh I worked for DVO uh I'm a community manager DUI-mode Django uh CMS Developer and
a call developer also off the uh Django project and a board member of the GenGO so foundation and there's my e-mail address you can find me as evil DMP on IRC and and so on
so um there's some people take quite seriously this idea that you should and right you'll documentation 1st and then the code should follow and it's something that's not discussable practice nearly as much as test driven development of that I didn't know actually know
anyone who that really does um documentation driven development or even talks about and I don't spend too much time on this but documentation
driven development is the idea that you know that reverses the typical priority of coding documentation you start with the code as stories of the documentation so the code and sort of documenting the code you code the documentation so it's rather like um test-driven don't development in that it puts what should be the case before what is actually the case and it helps establish a shared and easily accessible high-level overview of the work at hand and 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 can
binds the a programming efforts into a coherent narrative and the honest truth is I don't know very much more than this about documentation during development that 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 but some other senses in which documentation drives development so I want to have a look
at Django in the genome project and consider what documentation has meant for Jan goes development so the 1st thing we should say is and is not because this is a new observation that simply because everybody uh seems to
be on it is that Jangles documentation is exemplary and I'm not come across any other similar projects possibly any other project all with better documentation band Django and perhaps my experience is just a bit limited by the the anybody else seems to have come up with a project we
better documentation and gender has well you what what it actually is
so good about this documentation and 1st of all it's it's it's structured properly so structured into uh a very clear division between tutorials uh how to use reference material on topics and I'll discuss the implications of that a bit later that the structure of matters a lot within the structure it's very clear and consistent at its comprehensively covers just about everything all of it is
held to very high standards and so you need to work as hard on documentation as code if you want to get it accepted into the inter-gender itself it exemplifies the importance values and such as clarity
courtesy friendliness and finally and documentation Django is a process rather than a product and L. Ganesan we also want to talk about particularly and later so all of these are all the things that actually make the documentation good as documentation and the differences
it makes the effects 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 all programmers who were trying new things on help
and it also makes the development of Django itself easier and faster so in in other words giant documentation is very good for Jango without any doubt it
has been good for and 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 programmers and communities of programmers also develop and grow and improved and its programmers and communities of programmers that make the software grows and develops so what what this documentation mean for the development of uh communities and programmers and why documentation and manage matter to them well let's think about and Django community Chinese community like the software is is a
stable and mature and dependable you know where you are with Django community and the community is active it's
engaged and it's remarkably had united given that it's so large and is used by so many different people in so many different ways and places and like
all communities in has its difficulties sometimes but they're very rarely in Django crises that afflict some other communities in the very rarely in Django uh we we don't see engender these lingering ills that uh seemed to blight some other communities and I think 1 of the really that has bound this community community together is in fact John documentation
I think that when it comes to the development of the community that um uh genders documentation does fall very important things that I said earlier that it represents the attitudes of uh the
community but it is stronger than that the document take daggers documentation and all the care that Janco's documentation takes is an implicit contract but 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 and this
class is I think the deepest of all these points most important so start with that and everybody
learned programming who is a programmer have you had this experience of hesitating to ask for for help with a programming question perhaps on I'll see you on all somewhere online because you felt that the answer must be out there already if only you knew how to find it for so your hands up because your but because you had that experience yes OK good
yes I and others a signal that was misinterpreting and so and yeah that would be interesting who has had this experience of hesitating to ask for for help online because you felt yards was probably already out there if only you knew how to find it or search for export asked for it and you will be anxious that you might be invited by somebody who was a bit irritated to read the fucking manual by somebody who thought you're being lazy or stupid while there are I think most
people have experienced and you might be rights to hesitate because people who already know things can be remarkably forgetful about how they let them or about what it was like not to know that and so people are not always sympathetic and friendly to people who don't get to know the things that they do
and To the extent that programmers are um young men who full of confidence that did 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 um or perhaps
you ask the question and this is as you would have this you ask the question and someone's replied with a link to this sarcastic website do this they need medical that for website and it's that you you
put your search into and it does doesn't sarcastic simulation of so many sessions on the on Google and so I really hate I test that website I really hate everything it stands for because what it stands for is putting people down when they have a question 2 of
this but it stands for putting people
down who are asking for help in understanding something and it means telling them that that the reason they don't understand the things that they want to know is that they're too stupid
or lazy to so in so far as information and documentation content it's possible to
have to think and respond like that we see the content is out there especially in gender weight you know the content and if you ask a question about Django on I'll steal something probably the answer is in the documentation so if the temptation might be quite high for someone say well that the google it 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 but if you think of information and documentation just as content using will contents there and 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 by 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 sarcastic response is much less possible and we do see that response much less in Django than I've seen other uh
programming communities our IRC channels and e-mail it's a very friendly places and the experts of the community who had there regard information and documentation as activities that they are engaging in not as staff that people should red before wasting other people's time so so they may consider that information is something that they do documentation is something that they did not something some
stuff that exists out there so the information in this
model is regarded as and a communicative transaction between agents and information on this model demands that we respect values of the and clarity is what I'm saying clear intelligibility and am I saying in a way that the the other person can make sense of it uh relevance is what I'm saying actually relevant to the problem that the person talking to me and um comprehension has the other person and it can be other person understand what I'm saying answer to the question our attention to the needs and abilities of the other party do I speak in the same way to a complete beginners who doesn't even
know how to answer the question in the right in in the ideal way that that I would answer to somebody who is 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 from
information as of commutative transaction between me and you between me and the person trying to help I cannot pretend that telling them to read the fucking manual is in and it is informing them Basel informing them because
it's missing out all of that and sarcastically googling for them Ms. all of those points so good documentation
shows respect and there's a default
position but if someone doesn't understand the documentation the problem lies as much in the documentation or in the documentation rather than with the person who struggled to understand understand it it becomes an expression of those values so China's documentation set
standards and expectations in the tone for communication especially with uh communication with the less expert users of Django it's documentation is an assertion values that subsequently asserted
across and reflected but the whole Django community and I think what this means is that within the and trying to in this community that message and i included a lot of Python to because um it's more a or most obvious and Django but you do see it in Python in ways that you don't see in other programming communities but we think of of uh 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 use Python and gender so I said earlier that Janco's documentation has
being good for Jango but I think it's more than much more than merely good China's documentation forms its community and to inform something means literally to shape to inform to press the shape into something said triangles documentation has literally informed shapes the Django community it is determined by how the community has developed uh what sort of thing is developed into and is 1 of the things that continues to shape and drive the development of Django and that's the
kind of development I'm speaking of speaking of documentation driven development because the documentation is 1 of the things that determines the way Django is growing and developing I want to build their
migration here so the attitude toward the documentation In Django
has had a tangible difference that you can experience yourself not just when your thinking about it for writing talks and and analyzing it but in an ordinary everyday way uh and it's got to be quite forcefully sometimes especially when I speak to people outside our cozy world of of gender and I had an interesting experience and if I tell
people that I am a member of the Django core development team then them if they know what Django is that they have impressed and you know I'm a member of the general co-development him that's that's really cool and and then they say well and what what you will call and the documentation mainly or am I tell them about my job titles documentation manager and other programmers from outside the Python Django community sometimes find it a little bit harder to hide their sudden disappointment or even their embarrassments an embarrassment for me so
documentation it's like you know a moment ago they thought they being introduced to Superman it turns out it's only content after all the earth and and
sometimes you see a kind of the common expression on the faces in thinking like is this a joke in bad taste of uh that this person as admitting to this and I I swear that once or twice I had the impression that somebody was about to say that is not job so I'm I'm really
serious about this it's something that I encounter in some funny way and any it's
honestly as the why were admitting to having an unmanly personal will on among many personal habit like you know crying whining a
lot or writing a function when I should have written the castle using the wrong kind workflow 1 gets an analyst should I do all of this all of these things especially that crying and whining but to have people feel embarrassed for me and start to look desperate around the room for somebody more interesting to talk to because I admitted to them
that why many do is write documentation documentation tells you an awful lot about where it fits into the some people's picture of the world the when I tell somebody from Python Django communities that my main role is in common the documentation their reaction typically is the cool so there's is a real cultural differences between these communities I even so
I'll surprise I saw in some of the literature from I think some our sponsors of this conference that they were from inches and rock stars will I mean surprised to find that
here we 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 named as a rock stars you know whether this come
from why companies think they might benefit in some way from employing rock stars endangers the names of many famous for setting fire to buildings in the dead of nite and that's a very interesting metaphor on which to base your recruitment strategy all that you know the notion of employing rock stars the mind
boggles frankly there uh
was the defining characteristic of uh a rock star in excess of behavior is unreasonable demands an expectation that maybe underage girls will see with self-esteem issues might be willing or should be willing to offer them
sexual favors if the whole thing seems unbelievably mature and astounding
when you see it coming out of um not just at the start of being run by young men themselves have been stopped being teenage boys but corporations and you think maybe airline pilots would be a more appropriate metaphor Walsh
surgeons or chefs sort anything upholding which being disciplined thoughtful and highly skilled and be able to collaborate with other people well to achieve good outcomes would be a better metaphor for excellent programs but no and we have to be ninjas and rock stars you know once I Os Mr. Miller's actual fossils so
it's it's childish image image sure 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 will work and it makes him worse and it makes those companies and projects worst places to be some good come out of my
digression back that it's a genuine anything that Jangles
documentation has been uh part of what has helped Django avoid this kind of like and it is informed of the shape Django community into being a
better place it is developed it in back 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 developed get better and the question for many programmers is how the how do I developed how do i become a better programmer and it's true but quite an interesting observation that could Django documentation helps um Django programmers write better code but again I think the implications are part of wider than that so not just GenDiv everywhere documentation is an excellent way for newcomers to something to start contributing to it
to a source of 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 and writing documentation represents a really good and easy 1st step from being a user or something to being and active contributor to it especially in open source of 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 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 features 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 and part of uh a programmers to that development is to contribute and understand more documentation is an ideal way to do it will race the contributors understanding of the whole of and and the Django
project really does get all of this it really does understand all of this
genders document to actually about structure genders 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 pick particular section just as at well written code does and this website very well for maybe huge new uh all logic contributions may be an entire new section of the tutorial off tiny ones such as an aspect of some key functions that deserves more explanation so that if you fight the person in the new contributor and shows them where to go and how to do what they want to
contributions to Jangles documentation are taken very seriously and they held to the highest standards contributions to documentation and the
contributors make them receive as much support and encouragement encouragement ing and engagement as those who are contributing come In
many other projects documentation will be accepted just because it's documentation you know and the quality of it is not always an issue In Django documentation goes through the same ring that code goes through and you'll find if you're submitting documentation to gender this summer you saying well known you need to we need to change this will send it back to you and be prepared to sit there and go through a long um review process of many cycles to help you get the documentation just right for gender and so you you
as a documentation contributor will be taken as seriously as if you were contributing some key code it will 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 uh everybody who's on the Django core team has made substantial
contributions to Django my contributions have pretty much all been documentation contributions not so there are these
3 things that um
gender gets uh very rights the documentation guides its contributors it's taken seriously contributors are valued highly and and they're important because of this fact that most people say they
recognize and then in the end few people act as only they really believe it that documenting code is the best possible way to understand documenting code will make you a programmer who understands more things and understands them more detail and Django encourages developers to to write documentation and all of this
means that China not only gets more and better contributions to its documentation and on other projects to it also it's also very successful in advancing the skills on those who contribute to it if you want to learn how to contribute to open source software in Python there's probably no single better place to
start them by looking at the Django documentation and thinking could you make a contribution that because you will get a first-class
introduction in how to contribute to major project your work will be checked by somebody who is uh extremely thorough about it you will be guided engaged with every step of the way so if you want to start being an active contributor open-source of Python probably there isn't any way better to do it so this
is what I mean when I say that Django dollars documentation driven development I mean that through its documentation it develops In Advances improves both its community and
it's developers so that's the lesson from the Django project what can you do walk in your project due to reap some of the same room what room what can your project due to reap some of the same real rewards from its documentation well I don't think it's something that can be accomplished overnight uh and much of this is to with attitudes and attitudes of very
hard things to change and at the same time there are some of uh this actual steps you can take part easy and you keep taking them and keep taking them in the right direction eventually not 1st but in time attitudes will follow those steps so some practical things just very
briefly I mean but we have to talk about this more 1 is to structure documentation correctly so um if you look at the 1st page of the jagged documentation that explains this it doesn't get those 4 categories and mixed tutorials how to use reference of topic topics and and most documentation does the tutorial take somebody by the hand from not necessarily 0 but from unknown low starting point to a position of success so here's 1 task it might be just set of genome project will get you to the end of
it if you follow these steps were pretty much guaranteed success of the and that's completely different from how
to which is like uh recipe in in in a cookbook which requires that you understand that these 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 discursive material that the describes stuff it'll don't tell you how to do something they don't
list that bits and pieces of an API and they don't need you step by step through anything about they will give you a higher level uh uh overview and understanding of it and then I'll happily talked about that some more um if anyone's interested make documentation policies as rigorous as your code policies don't be afraid to batch documentation back its contributors that just because
some users submitted uh documentation that accepted take it seriously as seriously as you take code and asked for for it to be improved if it needs to be improved um you wouldn't accept some substandard posted under the same for documentation people appreciate being taken seriously substandard code can harm you applications but substandard documentation can harm your community which is worse document documentation
and make sure it's clear what is policies are not what you want from each section of it but what you expect of the contributors to it value your documentation contributors whether they're internal for external recognize and publicly make them according to the of your project if they've contributed enough value the activities of documentation and information and set aside time for them and if you all your project to your company a really serious about this there us some commitments that you can uh some real commitments so you can make you can make being 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 achieve the things on on on this page and right here in the
Python commonly uses with adopted by the way I should say here that
we cannot use redox so that can be I want to become and right here in the Python community we have 1 of the most important and valuable resources anywhere in the whole of the open source the
world of programming read the docks it's free it works brilliantly In the hands-on Python and
it's truly a scandalously underfunded so it's kept alive by Eric culture in the middle of the nite answering calls from his pager almost no money you been times in the past where he was losing money to keep read the docks afloat um
the company I worked for the year we want the sponsors of the the redox websites and so if you care about this kind of thing
than a small amount of money from your company would go an extremely long wait alongside their the docks part of the same family of activities this the right docks conference in Europe and the US absolutely brilliant really interesting uh conference really interesting to notice that in the right the the
docks conference about half of the speakers were technical writers um and most of the developers who were at the conference were from the Python Django communities and
again reflecting the attitude uh the esteem in which documentation is held in our communities and they also have the substance and the right bookstore so if I would like you to take
away 1 thing from the last uh 35 minutes or so it's it's thinks that information and documentation activities that we engage in and they not stop that we produce for all you thank FIL
OK we have some to some questions on thank you for the dog very
inspiring but I have I have a more pragmatic questions you idea of I don't use Django that much actually I almost don't use it but you probably have a lot of documentation rights so how do you keep the documentation in sync with the code for example I've heard people saying that docstrings are doomed to fail because they were will always the synchronized so how are you part
the body making documentation as important as the code so if you change the part of the code and it affected another part of the code you wouldn't change only 1 part and then the the other part of the you know some you thing that use the API you would be that in a broken state would you so in the same way why would you want to leave the the documentation in a broken state and uh the developers of China will just send it back to you you know you've change the code but without the documentation just like you wouldn't if it made tests fail you would isn't always obvious that if you if a developer changes is a bit of code that you have to intended govern the annotation is it no it it 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 that these there are a lot of people who were taking an interest in it and it's much harder for it to stick through the net so you know never pretend any of these things are easy but we were a lot of people who care about something it's certainly helps yeah person questions over there it's our
question is is the answer following that then you know it's actually rule is uh environment gender general project to fix it to get the best going and to fix the documentation with the patch so otherwise it will be refused thank you your question the kind of tying the purest crushed as well as some of the things doctests are a good tool to keep to the docks and think that the code all can you explain what you
mean by by don't test please and there's this thing implied select support compared to historical like right examples of docstring and test those examples and I'm wondering if you know how well it works out in practice because I know I have no idea used that and I think it's really important for documentation to be cure rated by humans so when you go to and this is the kind of references what program is
like writing bill of writing reference materials and because the describing all his his machine I made hero is parts and and you can put all the descriptions of that machinery into the machinery and have it automatically generated
but it's only useful for people who already have under a general understanding of what the thing is it's not to be used and use for anybody who needs a description of a kind of topic descriptions whom you need to know how to use it as a kind of general recipe and certainly would help a beginners looking for the tutorial so I guess they may have some place somewhere but for the vast pool rather than the rule and over there is is is is shaking head he have no function anyway I'm not I don't know about that but I know that for the most the documentation you're writing for human so the human being needs to write it the question over have you
heard of Jupiter having decision so the question is with developers maybe don't know English so well at the same level as maybe the 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 right documentation is cases they might write really good code but this well
um firstly uh even if people don't speak very good english they probably learned to before the 11th Python it is something that the non native uh speaker but secondly if they can be some of the most useful contributors to documentation because if you're writing for somebody whose 1st 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 uh some of the simplest language and give you directions for the weights that language needs to go in order to be comprehensible so this is understanding the other people who were reading your documentation as part of the process to it's not just a question of yeah his documentation understand if you can there's this the relationship between the 2 so very important part of that and thank structures good more
of a 1 statement firstly I realize Janga goes documentation because it kind of starts like ground 0 there's no assumptions about and the things that the users should should should have um also really appreciated the planned documentation as improvements in the last years but what nice before work in the last 10 years the Python is where you do with people outside of Python community you of course often felt fearless developer for you say you do documents because you're not spend your time program um I always wonder and you have a new voice is a conic there like a spear top-down thing in these organizations but do you have about 1 voice how you can kind of combat combat here
combat maybe ninjas should be sent into combat I I I I attitudes are the hardest thing To change Python Django are successful partly because of the documentation is 1 of the reasons that so many people coming in and if we can keep people coming in then we will be changing the culture just by having people part about community and inculcating them in the ways of our community other than that if somebody gives you look in horror because you write documentation at a party or meet up softly with 4 and you do with it that doesn't house
documentation in languages other than English is 1 of its it's just yesterday the documentation is translated in 2 French
completely and I think somebody is translating it into the Spanish at the moment that would have had the effect of that is the
transitions a hard job warning about that because of the previous comments about languages and stuff but some of them were actually that that that is a the person who asked me about non-native English speakers uh yeah you have another option is to translate all the documentation mother language that really is a labor of of love and then we got rich or famous by translating open source documentation into another language OK so do we have any
more questions yeah thank you for a great talk uh injuries due to modify the interpretation of and it's very very important and should be treated as a 1st class citizens were among ourselves from so it's more like a few of them the question of the effects of the very much to the few thank you very much for your time
and if you'd like to talk to me about any of this common and find of the very happy to talk about documentation and give practical suggestions about it and just 1 very last thing if I a very briefly I'm not an a Django wagtail or Django Oscar developer but if you are and what some quite exciting news for you to come and find me oft wasn't told me thanks once again for listening to me


  651 ms - page object


AV-Portal 3.9.2 (c7d7a940c57b22d0bc6d7f70d6f13fde2ef2d4b8)