 Thank you very much. So the title of my talk today is hi, my name is read me And that's some sort of a desperate attempt of myself of getting your attention I hope it worked. I realized it's very early in the morning still kind of after the first keynote So thank you very much for coming to my talk today But I also want to thank the organizers and the many volunteers for making this event possible. I think that's Really great. So thanks very much So just a little bit of myself to kind of set a context My name is Raphael. I currently live in Berlin. I lived in Scotland for a while. So I'm still Struggling with the weather here in Rimini I'm a maintainer and core developer of the cookie cutter project. I also contribute my time to the pie test project in Sometimes if I find the time and I Try to write blog posts on my personal blog at Raphael codes And during the day, I'm a software engineer at the mover group in Berlin You can find me on the internet using this Handle Hacker Broad on Twitter and on GitHub and I'll probably also post those lights linked to those lights later on on my Twitter So first off I want to talk a bit a little bit about something that happened just recently. So in June GitHub released a new project which is called the open source survey and it's a collection of It was a survey across many many repositories with many many people and they found some very interesting things which kind of Helped me to kind of make my point with this presentation today. So I just want to give some brief insights into what the survey was about So first of all, they had more than five five thousand Respondents to their survey. They were sourced from almost four thousand open source repositories on GitHub alone And there are also some responses from people from using other platforms and One of the biggest insights actually which was very very prominent and prominently displayed on their website Then later on was that documentation is highly valued but often overlooked and there were like a couple of follow-up blog posts Then on the internet people saying why this is people try to understand like why exactly don't we Care about documentation or what are the problems that we are facing and I find this really interesting Because it kind of brings me to why I'm giving us talk today, but first let's look a little bit about in the numbers. So first of all 93 of all of the respondents respondents said that incomplete or out documentation is a real problem and I would certainly agree with that The next point is really interesting for open source project as well licenses are by far 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 a license text I'll just close the tab and move on because If I don't know if I can actually use your project. Well, what's the point in spending any time looking further? But also documentation helps create inclusive communities So if you target a very specific problem, you might have a different kind of read me then if you are Maybe targeting a broader audience, but it's generally a good idea to kind of welcome people Explain what you're doing and make it as inclusive as as you possibly can And Then there's also another thing nearly a quarter of the open source community Reads and writes English less than very well. I didn't take part in the survey. So I don't know exactly what the question was but I'm not a native English speaker and I struggle a lot to write clear English language maybe in technical documentation But so I can to some degree I understand why people would say that I guess So what's the agenda for today? First of all, I want to talk with you about what exactly is a read me file Then I want to see why is a read me 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 create better read me files and what the facts will that have on your community? And then I want to talk a little bit just a little bit about things that you definitely don't want to have an a read Me file and as a takeaway later on I want to give you some advice Where to look for more information and how you can take the learnings from the stock and apply it to your own projects So let's start with the beginning. What exactly is a read me file? The read me file is many things, but it's first of all It's a text file and it lives with your code in your repository and it seems kind of obvious But at the same time not everyone might be familiar with this concept Most projects especially in the python communities use markdown or restructure text for their read me's which means you can still read the The texts the file contents just fine if they are formatted nicely, but platforms like github, gitlub, whatever They will render your actual text file and generate an html from that So it looks nicer and you can include images and whatnot 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 file called read me RST read me and D or just read me or read me TXT maybe But the name is always kind of what you would expect But a read me is more it's also what makes your projects first impression and that's why it's super important Super important because it makes it makes a big difference if people actually use your project later on or not so the adoption is Closely related to how well your read me is structured and welcoming and and so on It's also the first contact point for users who have problems with your software And I know from experience the cookie cutter project is quite popular and we get a lot of requests like people reporting bugs and whatnot and Like usually when people encounter a problem with your code a bug maybe They will not be in their happiest mood so I find it quite important to kind of take them by the hand on your read me and tell them what they can do about their problem and Use language that doesn't kind of make them even more aggressive. Maybe so it should be kind of understanding But also straight to the point where can they find information, but we'll look at the later on But a read me doesn't really have a standard there is no kind of convention or like a standard Yeah, so they might look very different for different projects and we'll have a look at some examples just in a bit Yeah, and communities have slightly different purposes for the read me as well But at the end of the day a read me always has the same 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 badges for the build status the code coverage the link to PI PI And then a logo for instance Then it goes on with features and example code and then more detailed information about Where you can find more information? I'm not saying that it's a great example I'm just trying to highlight right now that Those read me very quite a bit So if you're looking at the flask project which interestingly enough doesn't use any markup format It's just the txt But still it's a very very good read me because it contains all the information that a potential user needs And I think that's that's great So they just decided to not use any badges at all. It's really just the information on the content So I think that's great and It's similar for the Django project. So Django is a massive project, but the read me file itself It nearly fits on one screen So you will also find all the information that you need to learn more about the project So why is it so important? Why am I speaking here today? In my opinion you only get one chance to make a first impression that applies to many things in life Maybe but it also implies to your open source project because from my experience usually people find your project Maybe someone posted this on reddit or on hacker news Maybe and write snarky comments or maybe they will hear about at a conference about the project so the first thing that they usually do would go to your repository and Just because the platforms work that way they will present your read me as your home page if you will So I think it really has a big kind of influence and the adoption of your project So it can mean either your project will be successful or it could be a failure But what does it mean? Like what does it mean? Is it the failure if your read me is bad? So I think there is a correlation between those things. So first if you fail to appeal to potential users They won't be interested and want your project and your kind of story ends there already But then if you don't get any users for your project No one will actually give you feedback and you will struggle to really improve your project over time because you're the only one Who's working on the project and no one will tell you what's good or bad? And then lastly if no one is using your project and no one finds it interesting No one will ever even consider contributing to your project. So and if you if you want to do that I think that's a big problem But there's also more Read me's can be consumed in very different ways and what I mean by that is not everyone uses the github web UI for instance to read a read me For instance when I clone a project, I'm probably using my favorite editor to just read the text So kind of matters that not only the HTML is looking nice, but also that the text itself is good and well structured Yeah, so that's kind of what I meant And then there's also another thing how many of you have run such a command like something something and then dash dash help or Yeah, everyone or Like if you're using a Linux distribution or or a Mac maybe you probably run also something like this So you want so that invokes displays a manual page for you on those 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 ways so they either try a dash dash help or they try to see if there is a man page for it Or they try to look if there is a read me. So I think there's like without Really like doing it explicitly people will look for those kind of things. So I think that's that's what makes it so important And this is the thing that happened that was I think that So there is a technical writer She's called Mikey Ariel and she posted a blog post two years ago I think and she started this Twitter hashtag kind of of docs 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 your users because It's more than just Providing context. It's also about kind of taking people by there by the hand and welcome them to your project So so it kind of it shows that you care about your project that it's important to interact with your community In her blog post you also said that you're not alone words are work and I Would certainly agree with that. I'm a software developer. So I'm not technically Really educated and how to write technical content, but there are people who can help So I think that's an important thing that not only code contributions are important, but you can also ask for contributions patches for documentation and your read me and Sometimes that's really hard Because it's kind of maybe not our nature as software developers to care about these things So we kind of need to learn about it and get better at it just with just with writing code And it's it's it's not really that hard if you 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 from those communities So the main thing to remember from her blog post was that All of these efforts need to be collaborative. So it needs to be an effort from the community. It can't be just the maintainer Kind of looking after the read me It needs to be a combined effort and it needs to be simple and scalable If you are interested that's a link to the to her blog post But I'll post it later on as well. 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 throughout all of these points the most important thing for me is empathy so you as a creator of a project as a maintainer you need to think about why people come to your project Why are they interested? If they have a problem, it's important to kind of have this understanding for them of not being snarky or making stupid jokes or All of these things. So I think it's important to use empathy in in how you communicate with your community So the first thing that I find important is tell a story so What a read me can do what a code can't do is explain where does the project come from what problems? Does it solve? Why did you start it in the first place? Maybe how did it develop over time? Where does it stand today? and Then you kind of want to go into this part. How do you actually install it? How do you use it and where can you go from there and Then for any open source project. It's really important to also invite people to contribute to your project and help change The the maybe even the course of the project the direction have an impact and form a community I think that's important and Then the second most important thing I think is set expectations So maybe you have done that you found this blog post and then people say just run I don't know just run pip install whatever and then you get this error 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 minutes downloading this stuff And I invested my time and now I'm sitting here and it doesn't work You could have told me that right from the very beginning So that's what expectations are for So you explain what your problem does what I'm sorry what your project does what the problems it solves And then you can also point them to other projects because if you as a maintainer get those questions all over again I want to do this your project does something similar maybe but not quite So maybe you have some information what other projects you might want to have a look at And then you can also let your users know how material project actually is So if something is a weekend hack you should probably point it out on your read me So people don't do stupid stuff and run that stuff in production the next day after so it's important to kind of state somewhere what the development status is and This is actually a lesson that I learned In the cookie cutter project we used YAML as a configuration format and We got more and more complaints from users on Windows and also on Ubuntu at some point that they couldn't install a cookie cutter the reason being that they couldn't install PyYAML because Something broke Then we tried to use a fork of PyYAML RuralMill YAML But it also didn't work on other platforms and other architectures So I was so frustrated at some point that I wrote my own YAML parser And I knew that I will never implement the full specification because to be honest It's way too complex to write any parser for it and I have no idea how people actually do that but What I'm trying to say is here that I solved a very very particular problem that this Poryo library can only read cookie cutter config Files it's compliant with the YAML specification for those kind of structure that we expect on the config But it doesn't do more So YAML is actually a subset. Oh, sorry It's not so YAML is the format says that it's compatible with JSON So a YAML parser can always import a JSON file But Poryo can't What it also can't do it can't write YAML files So and people got really confused and they started thinking if 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 with if you want to I don't know use your cloud formation and Puzzle that or something like please don't do it So that's what I mean with expectations point of us early So people don't even think about using our project for something they shouldn't do Pre-requisites I think is also super important You want to be sure that people understand that they can't use your software under circumcised Conditions, so if your software is only tested, maybe it's technically Working on Windows, but you've never tried you might want to point that out So people don't have this super frustrating situation in which they just run into an error Python versions There are more and more projects who are only Python 3 compliant So you should point that out so people don't try to install it on Python 2 or vice versa like Couple of years back and also dependencies. So if your project uses Tools or technologies outside of the Python ecosystem, maybe a database driver client, whatever Maybe you should let them know so they don't install your project. Wonder why it doesn't work Let them know that they need to install something on their system first to use it so That's that's Code from a setup UI project. Sorry from a setup UI file from a Python project So they check for the platform and then raise a runtime error and I think it's good because they give a They give a good message an error message why it happens, but It would be even better if that was presented on the read me file So without actually using pip install you would 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 one way presented on the read me how you install your project and in the Python community That's mostly pip So cookie cutter is also available via homebrew via up get via conda But there's no point of really presenting that on the read me if there is pip and the main kind of Installation method is pip so you can have the other methods in your documentation, but just not on the read me So it should be concise and only one method And then you also as I mentioned you want to link to maybe Sections of your documentation in that case So it could be just this one kind of command pip install something and that's all you need But it should be presented on the read me I find Because there are still people who might not exactly know how you can actually install stuff from from the cheese shop So please present this information For other languages there might be go get for instance, so Just this one command I think is important to do know what's what happens and make it as easy as possible So if your kind of installation requires multiple steps, maybe you have a script in your Repository and the script does all of the work But users only need to run this one script. So make it easy and yeah Features you also want to talk about features because that's ultimately what gets users interested in using a software But don't list all of them So you don't want to crawl to like with pages and pages of awesome features Just list a couple of them. I find Maybe maybe seven. Maybe that's that's a good number And depending on how you present it. I think that's kind of as long as you get it on one screen I think that's it's kind of nice And then you want to have a getting started section. So how can you actually use your project? and That could be either like how you can use the command line interface But also how do you import your library? Maybe so give an example code and make sure that it actually works Because again, it's about expectations So if people then just create a script file on the file system want to run your example code and nothing works Well, you have the same effect kind of that people won't use a project and that's not what you want So this is how it could look like you explain it maybe a bit Yeah, there is that's a pie test plugin for instance You say yeah, there is this cookies fixture and then you show the code and you explain you can do this and this And if you want to find out more, please look at the documentation License that's a really important topic for any open source project because if your project doesn't have a license file 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 That's Data from the GitHub open source survey and 64 percent of the respondents said that an open source license is very important and decides over whether people actually use your project or not and as I mentioned before that also I had the same experience and 67% also said that it's what decides where they want to contribute. So if the license might not be the one that they Usually use or they feel comfortable with they might not contribute just because of the license Troubleshooting I think there should be an FAQ section in documentation But I wouldn't present it on the read me. I think so I would 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 People actually have 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 or lives on github and people mostly read your read me on the actually repository page There might be people who read the read me in that in the text editor So it's important to include the URL to your project. They might just download it from PI PI and then where's So where's the link to the actual repository? Where's the source code? and It's also important to point out way like ways of getting in touch with maintainers or other community members that could be maybe a Tag on stack overflow that could be an IRC channel Gitter or any other of those tools And I think it's also really important to talk a little bit about the community So who are 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 an expectation So can I expect some sort of? Well support or if I know that it's just a side project that or maybe a weekend hack or something I know that it will probably take a bit more time for them to respond to any issues that I might have and Also, how can you contribute to your project and how to become a core team member? GitHub is like it's moving towards this direction of making it better for open source projects, but Sometimes with if you don't have an organization for your project for instance, it's hard to invite people to your core development team So as of right now, I think you can Grant commit so write access to your repository but Like you don't have this fine separation of having yeah, I want to have people who can only Do bug triaging and they are not allowed to merge to master or so I think it's important to point out How can you actually? Become a core team member. How do you gain the trust? What do you need to do if you're interested? And there should always be a contributor code of conduct But it should should be there if you really care about it and it shouldn't be just like yeah, people talk about this stuff It's what you do nowadays, but it I mean it's it hasn't 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 then So if you use a 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 you get in touch? It could be an email or something else maybe Just an example from the PIP project, so that's their entire read me so it's it links to installation documentation Issue tracking so a couple of things that I mentioned already But then the next thing that they mention is the contributor code of conduct And I think that kind of shows that they care about this so what Shouldn't you do in your read me and this section is is really only a couple of slides because I don't want to No, let's let's just see 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 your project is doing I'm not using your project. I think that's that's very It says a lot about how much you actually care about the people that want to use your project So, please don't say a thing like just read the code your It might be an inflated ego or something, but I mean your code won't ever be this good that people Can use it in the same day they would use a beginner's tutorial for your project. So don't do that Also try to avoid words like easily obviously and just I Like I was going through all blog posts of mine and I used all of them multiple times in blog 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 is so awesome. It's so obvious what you need to do But there might always be people who don't find it obvious They might not find it easy to use they might be very new to Python or any other language So by using those words you You kind of make them feel like they're stupid and that makes them Unwelcome, so don't do that and the list goes on But for this talk I decided to just leave it with that. I think those are the most important points And I'd also don't want to discourage you from actually caring about this stuff So what can you do to improve your own projects? And I think there are a couple of things that you can do First of all, I think it's important to encourage any contributors to also submit patches for documentation and that also involves the readme so Kind of as a maintainer you want to let the people know that you care about the stuff And if there is a typo in your readme, it's not a bad thing to get a patch for fixing a typo I mean, that's an easy merge and why wouldn't you want to get this? So don't get angry at them for submitting a patch that only has a typo fix. 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 or learn more about from other communities So you as Python this does you probably know the website read the docs and The people behind read the docs decided that this is an important Kind of topic to talk about and they created the write the docs community and I'm wearing a t-shirt and I have stickers So they they have this this guide kind of for how can you get started with writing documentation? And there is it's not a lot of information, but I think that's all you need really to get started and Then there's also a couple of blog posts For instance, this one talks about the storytelling aspect of it that you want to explain to your users where you're coming from where you're going So I'll include the thing here for you And then there's also as I mentioned the write the docs community and in September 10th I think there is an event in and Prague for instance And there are a couple of hundred people 300 and they meet there and talk about all of these things and they come from very Different kind of backgrounds there might be software engineers There might be technical writers, so it's their kind of full-time job to care about this there might be Customer success engineers so people who care about that your customers can actually use your court There might be support people there might be all sorts of different people and I think that creates a very nice environment and Different points of view which is always important for this 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 read me because that's the most important document I think in the whole project And with that I have some stickers if you're interested Sorry Yeah, so I have some stickers if you're interested and then as a personal note I just wanted to mention this really briefly so if you maybe use the cookie cutter project It would be great if you could support it and if we can talk about this later on maybe just wanted to leave it here with us So that's me on the internet if you have any questions I'm happy to take questions now or later on or you can follow me in Twitter and ask questions there. Thank you Okay, I see a question Hello. Thank you for the great talk. You mentioned that if you have more than one comment to install your software Maybe you should have a script around that. Yeah, but if you're supporting Windows and Mac and Linux probably need to have more than one script because like bash doesn't work on Windows by default So you're going to have like oh, this is for Windows. This is for Mac and that's going back to have just one comment So it's not preferable to just have all the comments even if they're using each copy and paste Yeah, yeah, I think that's a that's a valid point So my kind of why I said that is because you wanted to make it as easy as possible So you could also have a separate document that says installation or something and it could be an executable script Which maybe it does all of the things Or you or you have just instructions written down But my point kind of is you don't want to overload people with information because say you're using Windows Why would I want to hear about how you use homebrew on Mac OS to install your project? And I think in that on the read me. I think there is no kind of room for this detail level of detail So is that an answer to your question? Cool. All right Hi, if we have a standardized Project layout with files like a read me license Contributing install and so forth Is it necessary to link those files like you have a license and Link in read me to license file or is it just enough to have this standardized Boulder layout So I would link to them So I think what I usually do is and in the Sorry so never mind. So I think like at the bottom of my project I usually Have a section that says this project is distributed under the terms of the MIT as Distributed as open free and open source software distributed under the terms of the MIT license And then the MIT license thing is because I use restructure text as a link Either to the official license text maybe on open source org or somewhere where the official license text is or You can also have a local link that so you just link to slash license or something and I would also like always start from the read me So I wouldn't link from the license to the read me, but the other way around and The reason why I would do that is because the if you kind of want only to rely on the structure People actually need to be experienced or familiar with this kind of structure So again, if you make it more explicit, it will be accessible to everyone even if they are completely new to the typical structure of open source projects Okay, any any more questions? We have time you say that if you Documentation has some small type is what happens everyone's human It's a very nice Bug for people to fix special beginners Do you have any good recommendation to how to lower the barrier for like people fix type was on the documentation? Because from my experience like oh this documentation has a type and then I need to fuck the repository Fix the type will then send the poor question. This is like too much in my opinion. Yeah, that's that's fair enough so If I'm not mistaken github made it so that you can also edit files on the web platforms So I think that's a step into the right direction. So it's easier for people without even having to use the comment line, etc But what you can also do is if in your community section if you have one you can So what we in cookie cutter say I think is every contribution is welcome. So even if it's just a typo Please don't hesitate. Please submit a pitch patch so just by saying that I think it encourages people enough to make the effort and They might be even willing to go through the hassle of cloning forking cloning and then all of that stuff As long as they feel that their work is appreciated and welcome I know from experienced like when I first made documentation changes to projects that I Didn't feel comfortable enough to make extra code changes. I would submit those documentation patches But then people said said to me This needs to work with this tool that magically Validates that our 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 maintainer you want to take people at their hand again So if they submit a patch and it fixes a typo But because they're editor for instance strips all of the white space and as a maintainer You might say I don't want to have all of these changes on all of those lines But only this typo Maybe you as a maintainer can you can kind of do the work then and remove the vice best changes again So they and it's important to leave their commits in the history so that they also feel kind of ownership And investment in your projects. So just of making it more accessible more easy and also that people feel appreciated You were also Talking about the fact that some people might not fully understand or read English for instance Are there any things that you might know of about like localizing read me files or things like that? Sorry, can you say the last part again? Are there any projects or things around localizing or internationalizing read me files or? So I know there are some projects which really make great effort of internal on like Contranslating documentation into different languages There is one major problem with this and it's when it gets out of sync And that happens quite easily if you have multiple copies of your documentation that kind of brings us back to this whole I Have this problem and then you ask the maintainer and I tell you well Just look at the documentation you say I'm using the Chinese version of the documentation and I just copy pasted the code and then so It's it's really hard. I think so what Maybe people can do is use Use simple constructs in English language so that even if you are not a native speaker Use language that everyone probably understands because after all as a Python person you write English words in your code so You might already have basic understanding of the language And on that note you shouldn't do stupid jokes in your documentation Because those are always like Really hard for people who are not native speakers to understand So I think that's what I learned over the years of doing that Okay, any other questions? No, well, then thanks. Bye