Hi, my name is README! - A Look at Why Docs are So Important

Video thumbnail (Frame 0) Video thumbnail (Frame 809) Video thumbnail (Frame 1669) Video thumbnail (Frame 3121) Video thumbnail (Frame 3925) Video thumbnail (Frame 6402) Video thumbnail (Frame 7442) Video thumbnail (Frame 13070) Video thumbnail (Frame 14144) Video thumbnail (Frame 17405) Video thumbnail (Frame 18572) Video thumbnail (Frame 20554) Video thumbnail (Frame 21753) Video thumbnail (Frame 29559) Video thumbnail (Frame 34146) Video thumbnail (Frame 35001) Video thumbnail (Frame 40381) Video thumbnail (Frame 42963) Video thumbnail (Frame 44006) Video thumbnail (Frame 45253) Video thumbnail (Frame 46257) Video thumbnail (Frame 47195) Video thumbnail (Frame 50787) Video thumbnail (Frame 51877)
Video in TIB AV-Portal: Hi, my name is README! - A Look at Why Docs are So Important

Formal Metadata

Title
Hi, my name is README! - A Look at Why Docs are So Important
Title of Series
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 license.
Identifiers
Publisher
Release Date
2017
Language
English

Content Metadata

Subject Area
Abstract
Hi, my name is README! - A Look at Why Docs are So Important [EuroPython 2017 - Talk - 2017-07-12 - PyCharm Room] [Rimini, Italy] When starting a new project, as developers we usually get right into hacking things, like tinkering with libs that we would like to learn or solving a particular problem as quickly a possible. Occasionally we also decide to publish the resulting package to PyPI, so that others can use our nifty code, submit a pull request and maybe even form a community around the project. If you're lucky someone might find it on the front-page of PyPI or the GitHub search or maybe even Hacker News or Reddit. What happens next is on you really. But what does that mean? Before jumping right to the command line and installing your package, those who are interested usually try to find out what problems the project is solving and how it can help them with their own. That's what your README file is for - it's most likely the first thing potential users read, that you control. A good README briefly and concisely explains what your software does, how it can be installed and what API it exposes. You also want to provide information on the requirements, the license it uses and how the project is managed. Who are you? How to get in touch to report problems and give feedback? Where can I find the Code of Conduct for this project? This talk is for everyone who is interested in working on open source projects and wants to know how documentation can help newcomers and more experienced users use your code and to encourage them to engage in the community
Self-organization Bit Quicksort Event horizon
Email Group action Event horizon Software developer Profil (magazine) Multiplication sign Blog Software Projective plane Core dump Pattern language Software maintenance
Point (geometry) Slide rule Server (computing) Dependent and independent variables Presentation of a group Open source Archaeological field survey Projective plane Open source Archaeological field survey Bit Internetworking Repository (publishing) Repository (publishing) Endliche Modelltheorie Computing platform
Point (geometry) Dependent and independent variables Service (economics) Open source Multiplication sign Projective plane Open source Bit Mereology 1 (number) Formal language Number Web 2.0 Degree (graph theory) Type theory Inclusion map Internetworking Different (Kate Ryan album) Telecommunication Right angle Reading (process)
Computer file Information Sound effect Bit Mereology Reading (process)
Point (geometry) Machine code Computer file Link (knot theory) Markup language Multiplication sign Similarity (geometry) Price index Machine code Formal language Medical imaging Root Different (Kate Ryan album) Electronic meeting system Cuboid HTTP cookie Computing platform Email Standard deviation Touchscreen Information Inheritance (object-oriented programming) Frustration File format Gender Projective plane Content (media) Bit Instance (computer science) Directory service Vector potential Membrane keyboard Repository (publishing) Software testing Object (grammar) HTTP cookie Reading (process)
Home page Presentation of a group Open source Repository (publishing) Hacker (term) Projective plane Video game Computing platform
Distribution (mathematics) Information Feedback Multiplication sign Projective plane Feedback Online help Instance (computer science) Vector potential Bookmark (World Wide Web) Vector potential Expected value Cross-correlation Data structure Logic gate Reading (process) Vulnerability (computing) Physical system
Context awareness Link (knot theory) Software developer Multiplication sign Patch (Unix) Projective plane Content (media) Bit Perturbation theory Binary file Scalability Machine code Twitter Word Word Natural number Blog
Point (geometry) Projective plane Reading (process)
Machine code State of matter Modal logic Direction (geometry) Multiplication sign Set (mathematics) Client (computing) Mereology Subset Expected value Arrow of time Error message Position operator Physical system Common Language Infrastructure Gamma function File format Software developer Hecke operator Parsing Message passing Configuration space Pattern language Right angle Physical system Point (geometry) Open source Computer file Device driver Online help RAID Product (business) Revision control Goodness of fit Latent heat Software testing Data structure Computing platform Condition number Computer architecture Serial port Information Projective plane Database Software Blog Computing platform Fiber bundle HTTP cookie Window Library (computing)
Point (geometry) Web page Presentation of a group Installation art Machine code Computer file Open source Link (knot theory) Sheaf (mathematics) Electronic mailing list Vector potential Machine code Formal language Number Expected value Hypermedia File system HTTP cookie Scripting language Link (knot theory) Touchscreen Block (periodic table) Projective plane Sound effect Bit Instance (computer science) Cartesian coordinate system Connected space Software Repository (publishing) Radio-frequency identification Sheaf (mathematics) HTTP cookie Reading (process) Library (computing)
Trail Server (computing) Machine code Open source Link (knot theory) Multiplication sign Direction (geometry) Source code Sheaf (mathematics) Set (mathematics) Machine code Dimensional analysis Product (business) Expected value Core dump Touch typing FAQ Extension (kinesiology) Dependent and independent variables Email Information Software developer Projective plane Open source Interactive television Bit Instance (computer science) Software maintenance Flow separation Arithmetic mean Repository (publishing) Sheaf (mathematics) Self-organization FAQ Quicksort Thermal conductivity Reading (process) Resultant
Point (geometry) Slide rule Multiplication Machine code Block (periodic table) Multiplication sign Projective plane Sheaf (mathematics) Electronic mailing list Formal language Data mining Word Blog Reading (process) Reverse engineering
Type theory Patch (Unix) Patch (Unix) Real number Projective plane
Point (geometry) Dataflow Software engineering Information View (database) Electronic program guide Instance (computer science) Event horizon System call Writing Coefficient of determination Process (computing) Integrated development environment Different (Kate Ryan album) Right angle
HTTP cookie
Point (geometry) Scripting language Default (computer science) Computer file Information Internetworking Integer Mereology Reading (process) Window Form (programming)
Greatest element Link (knot theory) Software Open source Lattice (group) Term (mathematics) Computer cluster Projective plane Sheaf (mathematics) Website Reading (process)
Vapor barrier Machine code Open source Computer file Direction (geometry) Patch (Unix) Multiplication sign Sheaf (mathematics) Set (mathematics) Formal language Web 2.0 Revision control Mathematics Bit rate Internetworking Synchronization Matrix (mathematics) Cloning Data structure Computing platform Form (programming) Constructor (object-oriented programming) Projective plane Instance (computer science) Line (geometry) Frame problem Type theory Word Personal digital assistant Website Right angle Text editor Spacetime
thank you very much so the title of my talk today is higher my name is written in the notes some sort of a desperate attempt of myself of getting your attention and I hope it works and I realize it's very early in the morning still kind of after the 1st king out so thank you very much for coming to my talk today the uh but I also want to thank the organisers and the many volunteers for making this event possible thing that's really great so thanks very much so just a little bit of myself to kind
uh set contexts and
monomers Raphael I currently live in the land by lifting Scotland for a while some still struggling with another year in Romania and I'm maintain and co-developer of the
cookie-cutter projects I also contributes far more time to the patterns project and sometimes survive under time and might try to write powerful so my personal blog profiles coats and and during the day and suffer engineer at the removal group and and you can find me on the
Internet using this uh handled Hough abroad on Twitter and get up and probably also post the slides modeling tools slides lateral movement the so 1st of all I want to
talk the bit of little bit about something that happened just recently so in June uh get-out produced and a new project which is called the open source survey and it's a collection ot was a survey across many many repositories with many many people and they found some very interesting things which kind of Help me to kind of make my point was this presentation today so I just want to give some brief insight into what the server was about so 1st of all that had more than 5 so 5 thousand respondents to the survey day um where sourced from almost 1000 open source repositories and get alone and there are also some responses from people from using other platforms and 1 of the
biggest inside actually which was very very prominent prominently displayed on the web so that electron was that documentation is highly valued but often overlooked and there were like a couple of follow up post and on the Internet people saying why a this is people tried to understand like why exactly don't we cares about documentation or 1 of the problems that we are facing and I find this really interesting some because it kind of brings me to why I'm giving us talk today
but 1st let's look at it in a little bit about the numbers so 1st of all um 93 of all of the that response said that incomplete or all documentation is a real problem and I will certainly agree that some the next 1 is really interesting for open source project well licenses are by far from the most important type of documentation for both users and contributors and I can speak from my own experience when I want to use a project and I struggle to find the license texts just close and move on because if I don't know if I can actually use your projects well what's the point in spending time with her father from but also documentation have strayed Inclusive Communities and so if you target a very specific problem you might they have a different kind of read me then if you are maybe targeting a broad audience but it's generally a good idea to kind of welcome people explain what you're doing and make it as inconclusive us as you possibly can and then there is also another thing nearly a quarter of the open source community and reads and writes English less than very well I didn't take part in the service I don't know exactly what the question was but uh I'm not a native english speaker and I struggle a lot too right clear um English language maybe and technical documentation from but so I can use to some degree I understand why people would say that's a guess so
what's the agenda for today 1st of all I want to talk with you about what exactly is a readme file then I wanted them to see why is a readme file important at all why would you care about it then the part in the middle will be about what makes a good read me so what can you actually do to trade better readme files and what effects will that have on your community and then I want to talk about it just a little bit about things that you definitely don't want to have a married file and as a takeaway later on I want to give you some advice from them where to look for more information and how we can take the learning from the distort and applied it to your own projects so let's start with the beginning
what exactly is a readme file readme file is
many things but it's 1st of all it's a text file and this is your coat in your repository and it seems kind of obvious but at the same time I'm not everyone might be familiar with this concept most projects especially in the Python communities is marked on a restructured text for their it means which means you can still read the and the text the file contents just find that therefore wanted nicely but platforms like attempted love whatever and they will render your them actual text file and generated HTML from that so the books by certain and you can include images and what the so that's how you would usually expect a project to be looking like so you have a root directory and then somewhere there will be some fire called readme artist you read Mandy or just read mean more readme txt membrane but the name was always kind of what you would expect but we use more it's also what makes your project's 1st impression and that's why it's super important um super-important because it makes it makes a big difference if people actually use your project it's wrong or not and so the adoption of closely related to how well you read me structured and what commands and so on it's also the 1st contact point for users who have problems with the software and and I know from experience and to cookie-cutter project is quite popular um and we get a lot of them because by people reporting box and what not and like usually when people encounter a problem with your code about maybe and they will not be in their happiest mood so I find it quite important to kind of take them by the hands on you read me and tell them what they can do about that problem problem and them use language that doesn't kind of make them even more aggressive Mary so it should be kind of understanding but also straight to the point where can I find information but look at the later on but the readme doesn't really have a standard there's no kind of convention or like it's a standard here so they might look very different for different projects and we'll have a look at some examples just innovates um yeah and communities have slightly different purposes for the admittance but at the end of the day reading always has a assigned kind of same kind of purpose it it tells a story and it tries to get people interested in your project so just looking at some examples because they really vary quite a bit so for the cookie cutter project you will find there is a header and you find edges for the bill status the court coverage of of the link to PI PI um and then a local for instance and then it goes on with features and example Croats and and then more detailed information about the way you can find more information I'm not saying that is a great example I'm just trying to highlight right now that that sweetness that vary quite a bit so looking at the flask projects which interestingly enough doesn't use any markup format it's just the cheeks you but still it's a very very good read me because it contains all the information that a potential user needs and and I think that's that's great so they just decided to not use any badges at all it's really just information on the content so I think that's great and it's similar for the Django project so gender is a massive project but the readme file it serves it nearly fits on 1 screen so you will also find all the information that you need to learn more about objects so why is it so important 1
speaking yesterday In my opinion you only get 1 chance to make a 1st impression that applies to many things in life maybe but it also implies the open source projects because from my experience usually people find a project maybe someone poses on reddit score on Hacker News maybe and write snarky comments or maybe they all hear about at a conference about the projects so the 1st thing that they usually do would go to your repository and just because the platforms work that way they will presenter read me as your homepage fuel so I think it really them as a big kind of influence on the adoption of your projects so it can mean either your project
will be successful and or could
be a failure but what does that mean like
what does it mean that the failure of read is bad and so I think there is a correlation between those things so 1st if you fail to appeal to potential users they won't be interested and want to use the project and your kind of story ends there already but then if you don't get any user project no 1 will actually give you feedback and you will struggle to really improve your project over time because you're the only 1 who's working on the project and no 1 will tell you what's good about and then lastly them if no 1 is using a project and no 1 finds it interesting no 1 will ever been was considered contributing to a project so and if you if you want to do that I think that's a big problem but there's also more their weakness can be consumed in very different ways and what I mean by that is not everyone uses the gates of what you I for instance to read read me and France's when I call a project on probably using my favorite is what to just read the text so kind of matter said not only the 2 miles looking nice but also that the text itself is good and what structure yeah that's so that's kind of what I meant some and then there's also saying how many of you have run such a command like something something and then Dutch Dutch help or everyone had or it like if you are using Linux distribution or or a Mac maybe you probably ran also something like this so you want so that in books it displays a manual page for you and the most operating systems and what I'm trying to say with this is that there is kind of this this expectation for from potential users that they find information about the project in those certain way so that you tried gestures help or they try to see there is a man page for it or they try to look at there's read me so I think there's like without really like doing it explicitly people will look for those kind of things I think that's that's what makes it
so important but and then this is the thing that happened so that was the thing that's uh so there is a technical writer she's called Mikey aerial and she posted a blog posts 2 years ago I think she started this Twitter hashtag kind of of stocks or it didn't happen and what it means is that if there is no documentation your project kind of doesn't exist so you you need to document things that are important to tell users because it's more than just providing context it's also about kind of taking people by their by the hand and welcome them to your project and show so it kind of this shows that you care about your project and it's important to interact with the community and in her blog post you also said
that you're not long words are work and I would certainly be that Siemens software developer of so I'm I'm not technically that really educated and how to write technical content but there are people can help so I think that's an important thing that's uh not only called contributions are important but you can also ask for contributions from patches for documentation and you read me and sometimes that's really hot um because it's kind of maybe not our nature as tougher developers to care about these things come so we kind of need to learn about it and get better at it just this just as a writing coach and it's it's it's not really that hard if he if you kind of invest a bit of time in reading from people who actually know how to do that and also maybe watch some conference talks on those and communities so the main thing to remember from my blog post was that's and all these efforts need to be collaborative out so it needs to be an effort from the community it can't be just to maintain our some kind of looking after the reading it needs to be a combined effort and it needs to be simple and scalable if you are interested that's link to
them come to about but I'll post electrons off so let's talk
about what makes a good read me and that's based on my opinion so people might have different understandings but but that's what I
feel and all of these points the most important thing for me is empathy so you as the creator of a project as a maintain on you need to think about why people come to your projects why are they interested um if they have a problem it's important to kind of have this understanding for them off not being smart you're making stupid jokes or or them all of these things so I think it's important to use empathy and and how you communicate with their community so the 1st thing that I find important to
tell a story so what we can do what a code can do is explain where does the project come from what problems doesn't solve why did you started in the 1st place maybe how they did it develop over time where does it stand today um and then you can I want to go into this part how do you actually and so that's how to use it and where can you go from there and then for any open source product it's really important to also invite people to contribute to the project and help change the maybe in the course of the project the direction have an impact from and form a community think that's important and then in the 2nd most important thing I think is set expectations so maybe you've done that you found this blog post and then people say just run I don't know just 1 to install or whatever and then you get this arrow saying well this doesn't work on Windows and you're like wow that's that's nice so I just spent like maybe a couple of installing the stuff and I invested my time and non sitting here and it doesn't work you could have told me that right from the very beginning so that's what expectations for so he explained what the problem that's what from a problem sorry what a project us what the problems it solves and then you can also point them to other projects because if years amounting get those questions all over again I want to do this your project does something similar maybe but it's not quite so maybe have some information what other projects you might want to look at and then you can also let your users know how much Europe project pictures so if something is a weak heck you should probably pondered out on a readme so people don't do stupid stuff and run that stuff and production the next day after so it's important to kind of states somewhere and what's the development status and this is actually a lesson that i loans that In the cookie-cutter project used young them as a configuration for and we get more and more complaints from users on Windows and also from the underwent at some point that they couldn't install a cookie cutter the reason being that they couldn't stop I young because something broke them then we tried to use a fork of primal wrongly on but also didn't work on other platforms and on other architectures so I was so frustrated at some point it I wrote my own Yamal parser and I knew that I will never implement the full specification because to to be honest it's way too complex to write right any parser for it and have no idea of the black to do that but I am but I'm trying to say here that I solve the very very particular problem that this point a library can only read cookie-cutter config fast is compliant with the gamma specification for those kind of structure that we expect in the conflict but it doesn't to more so young is actually a subset of sorry um it's not so young was this of as it is compatible Jason so Yamal parser can always imported Jason um but for you can't and what it also can do it can write down files so and people get really confused and they will start thinking of they should maybe use it for I don't know super important projects and I really had to point out this is not what this project is please don't use it for anything serious this if you want to go out all use your formation and positive something like please don't do it and so that's what I mean is expectations bundles of leaves so people don't even think about using a project for something should do prerequisites think is also super important you want to be sure that people understand that they can't use your software under circumstances and conditions so if Europe suffers only test that's maybe it's technically working on Windows but you've never tried you might put 1 to point that out so people don't have this super frustrating situation in which they just 1 and 2 in our the python versions them there are more and more projects were only patterns the compliance so you should find that out so people don't try to inside and Python to or vise versa like couple of years back and also dependencies so if you project uses tools are technologies outside of the Python ecosystem maybe a database driver clients whatever and maybe you should let them also they don't so your project wonder why it doesn't work and let them know that they need to install something on the system 1st uses so that's that's the 1 code from a set of QI project necessary from a set up you are far from apart projects and so they check for the platform and then raise alarm tomorrow and I think it's good because they give they give a good message an error message why it happens a lot it would be even better if that was presented on the readme file so without xt using
Pippin style you already know that if you're on windows it won't work I think that's that's would be even better installation
I think there should be 1 way presented on the read million start a project and in the Python community that's mostly pet so cookie-cutter
is also available via homebrew via AP gets the outcome but there's no point of representing that on the readme if there is to an the main kind of insulation method is that have so you can have the other methods in your documentation but just not on the readings so should become size and only 1 month and and then you also as I mentioned you want to link to media and sections of your documentation that as um so it could be just this 1 cannot of command pit instead of something and and that's all you need but it should be presented on the reader can find them because there are still people who might not that in all hurry connections to other stuff from from the she so so please presenters much have for other languages there might be a goal gaps for instance so them just assume command I think is important to to know what what happened and make it as easy as possible so you're kind of installation requires multiple steps maybe have a script in Europe from the repository and the script does all of the work them but users only need to run this 1 script to make it easy and now features you also want to talk about features because that's ultimately what gets users interested in using software but don't this all of them so you don't want to spare the crawled from like MIT pages and pages of all some features and just list a couple of them defined and maybe maybe 7 maybe that's that's a good number of them and depending on how you presented I think that's kind of as long as you get it on 1 screen applicants scandalous and you want to have a getting started section so how can you actually use your projects them and that could be either like how you can use the command line interface but also hold the import your library maybe some so given example code and make sure that it actually works uh because again it's about expectations so if people than just create a script file on the file system want to run you example code and nothing works so well you have the same effect kind of that people want use of projects and that's not what you want so this is how it could look like he explained it maybe a bit yeah there's that's the practice block and for instance you say yeah there's this cookies fixture and then you show the colony explained you can do this and this and if you want to find out more please look at the documentation license them that's a really important topic for any open source project because if your project doesn't have a license file uh you kind of don't allow people to actually use your project so it's important to point this out and link to the full license text
and that's the data from the ticket of open source server and 64 per cent of the respondents said that an open source license is very important and decides of whether people actually use a product amount and as I mentioned before that also I had the same experience and 67 per cent also said that it's what decides whether they want to contribute so the license might not be the 1 that day and usually use or that you comfortable as they might have contributed our just because of a license troubleshooting
I think there should be an FAQ section and documentation but I wouldn't be presented on the reading I think so I would read a link to it I think that would be a nice way of doing that but it's important to have a dedicated troubleshooting section so if if people active problems they know where to look and where to find this information please also have a link to your issue tracker like even if the project exists all this get top and people mostly read carried me on convection repository approach there might be people who read the readme ended in the text torso so it's important to include to your out projects they might just downloaded from PI PI and then where's so where's the link to the X repository rest source code it is also important to point out way like ways of getting in touch with maintenance or other community members that could be maybe uh tag on StackOverflow that could be an Irish Sea channel picture of any of those and tools from anything it's also really important to talk a little bit about the community and so were the people behind the project I personally find it really interesting to know whether the people working on the project are doing that during their working hours or if it's a spare time project because for me that to some extent sets also on expectations so can I expect some sort of them well supports or if I know that it's just a side project at from idea we can tackle something on all that it will probably take a bit more time for them to respond to any issues that might have and also how can it contribute to your project and how to become a core team member in give how this like it's moving towards direction of making it better for open source projects but sometimes with if you don't have to have an organization for a project for instance it's hard to invite people to your core development team so as of right now I think you can and grant commits so write access to your repository but but you don't have this find and separation of having yeah I want to have people who can only do bark triaging and they are not allowed to merge 2 master or so I think it's important to point out how can you actually become a core remember how do you gain the trust what you need to do if you're interested in and this should always be a contributor code of conduct but it should be should be there if you really care about it and that it shouldn't be just like yeah people talk about the stuff uh it's what you do nowadays but I mean it's it has and it has a meaning so if you're not familiar with that it kind of gives a guideline on how you interact with your community things that you shouldn't do and if you if you misbehave kind of what happens on um so the user and contributor code of conduct it's also important to provide a contact information of if something happens if you want to report something how can it and touch it could be an e-mail or something else and just an example from that the project so that's their entirety results that links to installation documentation that issue tracking so a couple things that I mentioned already but then the next thing that dimension as the country a code of conduct and I think that kind of shows that they care about is so what shouldn't you do
in your reading and this section is is really only a couple of slides
because I don't want to and know that's that's a C like so please please please please don't say things like just read the code because code is not documentation and if I have to read your code if I have to reverse engineer what a project is doing I'm not using a project I thing that's that's very it says a lot about whole much actually care about the people that want to use project so please don't say a thing like just read the code York yeah it might be an inflated you or something but I I mean your code won't ever be this good that people can use it in the same they they would use a beginner's tutorial for a projected onto the also try to avoid words like easy the obviously and just and I like I was going through all blog post of mine and to use all of them multiple times and block posts it's just because you are kind of the creator of the project and you want to promote it as being easy you want to say yeah this this API so also met so obvious what you need to do but there might always be people who don't find it obvious that it might not find it easy to use they might be very new to Python or any other language so by using those words you the kind of make them feel like they're stupid and that makes some them unwelcome some so don't do that and the list goes on and but for this talk I decided to just leave it at that then goes on the most important points um and but also don't want to discourage you from actually caring about the stuff that so what can you do to improve your own
projects nothing there are a couple of things that can do
1st of all I think it's important to encourage any contributors to also submit patches for documentation and that also involves the real thing so kind of as maintained you want to tap let the people know that you care about stuff and if there is a type when you read me it's not a bad thing to get a patch for fixing the title I I mean that's an easy merchants why wouldn't you want to get so don't get angry at them for submitting a patch that only has a type of fixed I think that's that's great so it helps make your project more accessible and more welcome and then you can
also read what all and more about from other communities and so you this path this does you probably know the website greet the docks and just the people behind the read the dogs decided that this is an important for um kind of topic to talk about them and they created the writer docs community and wearing a T-shirt and I have stickers that further and so they they have this this guide kind of for how can you get started was writing documentation them and there is it's not a lot of information but I think that's all you need to really to get started and then there's also a couple flow posts so for instance this 1 talks about the story telling aspect of it that you want to explain to users we're coming from where you're going and so I'll include thank you for you and then there's also as I
mentioned the right ducks community and in September 10th I think there is an event in in Proc for instance and there are a couple of hundred people 382 and talk of all of these things and they come from very different kind of back from some of the software engineers there might be technical writer so that's the kind of full-time job to care about this them there might be some customer success engineer so people care about that your customers can actually use your call and there might be support people there might be all sorts of different people and the thing that creates a very nice environment and a different points of view which is always important for this and empathy kind of thing that I talked about earlier so with this talk I kind of
wanted to encourage you to as Python engineers to care about documentation and especially about the readme because that's the most important document a thing in the whole project and
with that I have some stickers if you're interested in um that uh yes so I have subsequence of
interest and then I as a personal note I just wanted to mention this very briefly and so if you may be used to cookie-cutter projects and it would be great if you could support it and if we can talk about later on I just want to leave it here for the
and so that's me on the Internet's if you have any questions I'm happy to take questions now later on or you can uh form integer and ask questions but few
be on mission and at the well thank you for the great told you mention that if you have more than 1 common to style itself maybe should have a script of that kept were if you spot in Windows and Mac and Linux each have more than 1 scripts because like best isn't walkin windows by default only which have like 0 this is following this is from that and that's going back to have just 1 comment this is not preferred use have all the commons even if you use each copy and paste there yeah I think that's a that's a valid point so my kind of why said that this because you wanted to make it as easy as possible so you could also have a separate document that says installation or something that could be an executable script which made it does all of the things I have them or you are you have just instructions written down there but my point kind of this you don't want to overlook people with information because say you're using Windows why would I want to hear about how you use homebrew on my questions a project and I think in that's on the reading I think there's no kind of room for this detailed level of due on the so is a an answer to your question called part yeah hi you we have a standardized so logically out uh read flies like a readme license contributing in style and so for the is it necessary tool in those files like co you have a license and lean in read me license file or is it just enough to have the standardized of Boulder Leo um so so I want to link to them um so I think what I usually do is and the and some so it
but sorry so now want so I
think like at the bottom of my project are usually some have a section that says and this project is distributed under the terms of the MIT lattice distributed as open free and open source software distributed under the terms of the MIT license then the MIT licensing this because I use reStructuredText is a link them either to the official license text maybe on open source of Oracle somewhere where the official license sexes or you can also have low local link that so you just link to slash license or something and and I would also like always start from the read me so I Wendling from the license to the readme but the other way around them
and the reason why I would do that is because if you kind of want only to rely on the structure people actually need to be experienced are familiar with this kind of structure so again if you make it more explicit will be accessible to everyone even if they are completely new to you the typical structure of open source projects so this this again it any more questions I won't we have time so what we say that but if you up that mentation has some small time what happens the evidence for the human how it so the nice well but for people to free special begins that hot do you have any good recommendation to hold to lower the barrier for like people fixed by presume that the plantation because fomites rooms like a locus differentation has applied and then I need to fault was sorry could fix the pipe will then send the police and the site too much my opinion here that's that's fair enough from so if I'm not mistaken could have made it so that you can also edit files on the web platforms so something that's it step into the right direction so it's easier for people without even having to use a command-line set from them but what you can also do this if you in your community section if you have 1 you can come so what we in cookie-cutter say I think is every contribution is welcome so even if it's just a typo um please don't hesitate please submit pitch patch just by saying that I think it encourages people enough to make the effort and they might be willing to go through the hassle of cloning forking cloning and all of that stuff as long as they feel that their work is appreciated and welcomed uh I know from experience like when I 1st met documentation changes to projects that I know didn't feel comfortable enough to make of cold changes I would submit both documentation patches but then people 7 said to me this needs to work with this tool that magically validates that all documentation is working and you need to do this and this and this and this is really discouraging so I think you kind of as a mentality you want to take people at their hand again so it's a submit a pension matrix is a type form but because they're editor for instance strips all of the white space and is maintaining a you might say I don't want to have all of these changes all of those lines but only this type of maybe you as an antenna can you can kind of do their works and removed the wise prestigious again so they and it's important to leave their comments in the history so that they also feel kind of ownership and investment in your so just of making it more accessible more easy and also the people feel appreciated and you were also and talking about the fact that some people might not fully understand or read English frames and there are there any things that you might know of about battle creating we fight and things like that I'm sorry case last pouring that other EU project of things around the localizing are internationalising comedy Pfizer so I know there are some projects which really make rate of 4 of the Internet on on like con translating documentation in 2 different languages there is 1 major problem with this and when it's gets out of sync and that happens quite easily if you have multiple copies of the documentation that kind of brings us back to this whole um I have this problem and then you ask them antenna tell you well just look at the documentation is say I'm using the Chinese version of the documentation and I just copy-paste the codon and so it's it's really hard I think and so what who maybe people can do is use use simple constructs in English language so that even if you're not a native speaker use of everyone probably understand because after all as a Python person you write English words in your code so you might already have basic understanding of the language from the and on that note you shouldn't do stupid jokes in your documentation and because those are always like really hard for people who are not native speakers to understand it so I think that's what I learned over the years of yeah yeah OK and any other questions the know what then sense of very
Feedback