Hi, my name is README! - A Look at Why Docs are So Important
Pierzina, Raphael
Hi, my name is README! - A Look at Why Docs are So Important 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
 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 realize 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. It was 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 Romania. I'm a maintainer and core developer of the Cookie Cutter project. I also contribute my time to the Pytest project. And sometimes if I find the time, and I try to write blog posts on my personal blog at Raphael.coats. 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 the slides, link to the slides later on on my Twitter. So first off, I want to talk 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, or 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 5,000 respondents to their survey. They were sourced from almost 4,000 open source repositories on GitHub alone. And there are also some responses from people using other platforms. And one of the biggest insights, actually, which was very, very prominently displayed on their website then later on, was that documentation is highly valued but often overlooked. And there were a couple of follow-up blog posts then on the internet, people saying, why this is? People try to understand 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 a talk today. But first, let's look a little bit about the numbers. So first of all, 93 of all of the 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 the 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 than 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 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, 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? And 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 effects 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 in 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? A read me file is many things, but first of all, it's a text file and it lives with your code in your repository. And that 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, which means you can still read the text, the file contents, just fine if there are formatted nicely, but platforms like GitHub, GitLab, 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, MD, 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 project's first impression and that's why it's super important. Super important because 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 well-coming 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 it later on. But a read me doesn't really have a standard. There is no kind of convention or like a standard. So they might look very different for different projects. And we'll have a look at some examples just in a bit. 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 purpose. 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 PIPI, 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 vary 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 great. So they just decided to not use any badges at all. It's really just the information and 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 your 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 applies 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 writes Naki comments. Or maybe they will hear about at a conference about your 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 homepage, 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? What does it mean? The failure of 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. And if you want to do that, I think that's a big problem. But there's also more. Read me 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 or read me. For instance, when I clone a project, I'm probably using my favorite editor to just read the text. So it kind of matters that not only the HTML is looking nice, but also that the text itself is good and well-structured. 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 a Mac, maybe, you probably run also something like this. So you want, so that even folks, it 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 expectation from potential users that they find information about the project in those certain ways. So they either try 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 is like, without really like doing it explicitly, people will look for those kinds of things. So I think that's what makes it so important. And this is a thing that happened that was, I think, 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 off 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 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 their hand and welcome them to your project. So it kind of shows that you care about your project, that it's important to interact with your community. In her blog post, she 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 in how to write technical content. But there are people who can help. So I think that's an important thing. 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 writing code. And it's not really that hard 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 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 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 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 do is explain where does the project come from? How does it solve problems? 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 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, oh, wow, 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 explain what your problem does, 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 cookie cutter. The reason being that they couldn't install PyYAML because something broke. Then we tried to use a fork of PyYAML, 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 Poyer library can only read cookie cutter config files. It's compliant with the YAML specification for those kind of structure that we expect in the config, but it doesn't do more. So YAML is actually a subset, sorry. So YAML is, the format says that it's compatible with JSON. So a YAML parser can always import a JSON file. But Poyer can't. What it also can do, it can't write YAML files. 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 parser or something. Like, please don't do it. So that's what I mean with expectations. Point of all, early, so people don't even think about using a project for something they shouldn't do. Pre-requisites I think is also super important. If you want to be sure that people understand that they can't use your software under circumstance 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 a 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 code from a setup py 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 good message, an error message, why it happens. But it would be even better if that was presented on the readme 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 would be even better. Installation. I think there should be one way presented on the readme how you install your project. And in the Python community, that's mostly pip. So cookie cutter is also available via homebrew, via upget, via conda. But there's no point of really presenting that on the readme 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 readme. 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 readme I find. Because there are still people who might not exactly know how you can actually install stuff from the G-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 know 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 your software. But don't list all of them. So you don't want to crawl to pages and pages of awesome features. Just list a couple of them, I find. Maybe seven. Maybe 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 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 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, that's a PyTest 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% 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 whether 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 me in the text editor. So it's important to include the URL to your project. They might just download it from PyPI and then where's the link to the actual repository? Where's the source code? And it's also important to point out 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, GitR 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 support or if I know that it's just a side project or maybe a weekend tag 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 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 are interested? And there should always be a contributor code of conduct. But it 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 I mean, 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 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 the entire read me. So it links to installation documentation, issue tracking. So a couple of things that I mentioned already. But then the next thing that I mentioned 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 really only a couple of slides because I don't want to... Let's just see. So please, please, please, please don't say things like just read the code. Because code is not documentation. But 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 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 things like just read the code. 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 was going through all blog posts of mine and I used all of them multiple times on 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 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 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 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 read me. So kind of as a maintainer, you want to let the people know that you care about this stuff. And if there is a typo in your read me, 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 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 Pythonist 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 have 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 thank you 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 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 code. 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 readme, 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 that. 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 into a journal 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. But if you're supporting Windows and Mac and Linux, probably you 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 comment paste. Yeah. Yeah, I think 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 does all of the things. 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? 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 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 folder layout? So I would link to them. So I think what I usually do is in the, sorry, never mind. So I think at the bottom of my project, I usually have a section that says this project is distributed under the terms of the MIT, distributed as 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 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 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 more questions? Well, we have time. You say that if your documentation has some small type, 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 people fix type on the documentation? Because from my experience, like, oh, this documentation has a type. And then I need to fork the repository, fix the type, then send the pull request, and this is too much in my opinion. Yeah, 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, et cetera. But what you can also do is if in your community section, if you have one, you can, so what we in Cookiecutter say, I think, is every contribution is welcome. So even if it's just a typo, please don't hesitate. Please submit a page. 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 forking, cloning, and all of that stuff, as long as they feel that their work is appreciated and welcome. I know from experience, like, when I first made documentation changes to projects that I didn't feel comfortable enough to make actual code changes, I would submit those documentation patches. But then people 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. 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 white space 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 about like localizing readmifis or things like that? Sorry, can you say the last part again? Are there any projects or things around localizing or internationalizing readmifis or? So I know there are some projects which really make great effort on like translating documentation into different languages. There is one major problem with this, and it's when it gets out of sync, and it 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 they 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 really hard, I think. So what maybe people can do is use simple constructs in English language so that even if you're 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? Nope. Well, then, thanks, Afair. Thank you. Thank you. Thank you. Thank you. Thank you. Thank you. Thank you. Thank you. Thank you. Thank you.
 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 realize 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.  It was 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 Romania.  I'm a maintainer and core developer of the Cookie Cutter project.  I also contribute my time to the Pytest project.  And sometimes if I find the time, and I try to write blog posts on my personal blog at  Raphael.coats.  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 the slides, link to the slides later on on my Twitter.  So first off, I want to talk 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, or 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 5,000 respondents to their survey.  They were sourced from almost 4,000 open source repositories on GitHub alone.  And there are also some responses from people using other platforms.  And one of the biggest insights, actually, which was very, very prominently displayed  on their website then later on, was that documentation is highly valued but often overlooked.  And there were a couple of follow-up blog posts then on the internet, people saying,  why this is?  People try to understand 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 a  talk today.  But first, let's look a little bit about the numbers.  So first of all, 93 of all of the 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 the 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  than 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 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, 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?  And 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 effects 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 in 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?  A read me file is many things, but first of all, it's a text file and it lives with your  code in your repository.  And that 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, which means you can still read the text, the file contents, just fine if there  are formatted nicely, but platforms like GitHub, GitLab, 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, MD, 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 project's first impression and that's why it's super important.  Super important because 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 well-coming  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 it later on.  But a read me doesn't really have a standard.  There is no kind of convention or like a standard.  So they might look very different for different projects.  And we'll have a look at some examples just in a bit.  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 purpose.  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 PIPI, 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 vary 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 great.  So they just decided to not use any badges at all.  It's really just the information and 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 your 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 applies 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 writes Naki comments.  Or maybe they will hear about at a conference about your 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 homepage,  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?  What does it mean?  The failure of 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.  And if you want to do that, I think that's a big problem.  But there's also more.  Read me 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 or  read me.  For instance, when I clone a project, I'm probably using my favorite editor to just read  the text.  So it kind of matters that not only the HTML is looking nice, but also that the text itself  is good and well-structured.  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 a Mac, maybe, you probably run also something  like this.  So you want, so that even folks, it 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 expectation from potential  users that they find information about the project in those certain ways.  So they either try 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 is like, without really like doing it explicitly, people will look for  those kinds of things.  So I think that's what makes it so important.  And this is a thing that happened that was, I think, 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 off 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 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 their hand and welcome them to your project.  So it kind of shows that you care about your project, that it's important to interact with  your community.  In her blog post, she 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 in how to write technical content.  But there are people who can help.  So I think that's an important thing.  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 writing code.  And it's not really that hard 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 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 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 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 do is explain where does the project come  from?  How does it solve problems?  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 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, oh, wow, 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 explain what your problem does, 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 cookie cutter.  The reason being that they couldn't install PyYAML because something broke.  Then we tried to use a fork of PyYAML, 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 Poyer library can only read cookie cutter config files.  It's compliant with the YAML specification for those kind of structure that we expect  in the config, but it doesn't do more.  So YAML is actually a subset, sorry.  So YAML is, the format says that it's compatible with JSON.  So a YAML parser can always import a JSON file.  But Poyer can't.  What it also can do, it can't write YAML files.  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 parser or something.  Like, please don't do it.  So that's what I mean with expectations.  Point of all, early, so people don't even think about using a project for something  they shouldn't do.  Pre-requisites I think is also super important.  If you want to be sure that people understand that they can't use your software under circumstance  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 a 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 code from a setup py 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 good message, an error message, why it happens.  But it would be even better if that was presented on the readme 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 would be even better.  Installation.  I think there should be one way presented on the readme how you install your project.  And in the Python community, that's mostly pip.  So cookie cutter is also available via homebrew, via upget, via conda.  But there's no point of really presenting that on the readme 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 readme.  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 readme I find.  Because there are still people who might not exactly know how you can actually install  stuff from the G-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 know 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 your software.  But don't list all of them.  So you don't want to crawl to pages and pages of awesome features.  Just list a couple of them, I find.  Maybe seven.  Maybe 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 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 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, that's a PyTest 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% 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 whether 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 me in the text editor.  So it's important to include the URL to your project.  They might just download it from PyPI and then where's the link to the actual repository?  Where's the source code?  And it's also important to point out 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, GitR 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 support or if I know that it's just a side project or maybe  a weekend tag 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 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 are interested?  And there should always be a contributor code of conduct.  But it 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 I mean, 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 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 the entire read me.  So it links to installation documentation, issue tracking.  So a couple of things that I mentioned already.  But then the next thing that I mentioned 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 really only a couple of slides because I don't want to...  Let's just see.  So please, please, please, please don't say things like just read the code.  Because code is not documentation.  But 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 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 things like just read the code.  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 was going through all blog posts of mine and I used all of them multiple times on 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 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 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 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 read me.  So kind of as a maintainer, you want to let the people know that you care about this stuff.  And if there is a typo in your read me, 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 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 Pythonist 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 have 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 thank you 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 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 code.  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 readme, 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 that.  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 into a journal 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.  But if you're supporting Windows and Mac and Linux, probably you 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 comment  paste.  Yeah.  Yeah, I think 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 does all of the things.  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?  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 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 folder layout?  So I would link to them.  So I think what I usually do is in the, sorry, never mind.  So I think at the bottom of my project, I usually have a section that says this project  is distributed under the terms of the MIT, distributed as 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 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 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 more questions?  Well, we have time.  You say that if your documentation has some small type, 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 people fix type on  the documentation?  Because from my experience, like, oh, this documentation has a type.  And then I need to fork the repository, fix the type, then send the pull request, and  this is too much in my opinion.  Yeah, 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, et cetera.  But what you can also do is if in your community section, if you have one, you can, so what  we in Cookiecutter say, I think, is every contribution is welcome.  So even if it's just a typo, please don't hesitate.  Please submit a page.  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 forking, cloning, and all of  that stuff, as long as they feel that their work is appreciated and welcome.  I know from experience, like, when I first made documentation changes to projects that  I didn't feel comfortable enough to make actual code changes, I would submit those documentation  patches.  But then people 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.  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 white space  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 about like localizing readmifis or things like that?  Sorry, can you say the last part again?  Are there any projects or things around localizing or internationalizing readmifis or?  So I know there are some projects which really make great effort on like translating documentation  into different languages.  There is one major problem with this, and it's when it gets out of sync, and it 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 they 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 really hard, I think.  So what maybe people can do is use simple constructs in English language so that even  if you're 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?  Nope.  Well, then, thanks, Afair.  Thank you.  Thank you.  Thank you.  Thank you.  Thank you.  Thank you.  Thank you.  Thank you.  Thank you.  Thank you.
Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_0_155.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_156_551.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_552_3131.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_3132_7835.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_7836_14483.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_14484_14591.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_14592_20759.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_20760_20975.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_20976_21755.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_21756_22847.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_22848_27659.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_27660_27779.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_27780_29567.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_29568_31871.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_31872_31991.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_31992_35231.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_35232_37139.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_37140_41615.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_41616_43115.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_43116_47471.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_47472_47519.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_47520_47591.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_47592_47639.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_47640_47687.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_47688_47759.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_47760_47807.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_47808_48251.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_48252_48311.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_48312_48371.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_48372_48419.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_48420_49187.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_49188_49775.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_49776_49847.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_49848_49931.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_49932_50531.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_50532_50591.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_50592_51887.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_51888_52367.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_52368_52703.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_52704_52751.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_52752_52823.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_52824_53711.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_53712_53759.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_53760_54299.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_54300_55763.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_55764_56591.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_56592_56651.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_56652_56783.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_56784_56903.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_56904_57119.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_57120_57167.png Raphael_Pierzina_-_Hi__my_name_is_README__-_A_Look_at_Why_Docs_are_So_Important_sQ9H2h-y_p4_57168_59373.png
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 realize 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. It was 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 Romania. I'm a maintainer and core developer of the Cookie Cutter project. I also contribute my time to the Pytest project. And sometimes if I find the time, and I try to write blog posts on my personal blog at Raphael.coats. 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 the slides, link to the slides later on on my Twitter. So first off, I want to talk 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, or 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 5,000 respondents to their survey. They were sourced from almost 4,000 open source repositories on GitHub alone. And there are also some responses from people using other platforms. And one of the biggest insights, actually, which was very, very prominently displayed on their website then later on, was that documentation is highly valued but often overlooked. And there were a couple of follow-up blog posts then on the internet, people saying, why this is? People try to understand 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 a talk today. But first, let's look a little bit about the numbers. So first of all, 93 of all of the 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 the 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 than 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 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, 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? And 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 effects 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 in 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? A read me file is many things, but first of all, it's a text file and it lives with your code in your repository. And that 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, which means you can still read the text, the file contents, just fine if there are formatted nicely, but platforms like GitHub, GitLab, 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, MD, 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 project's first impression and that's why it's super important. Super important because 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 well-coming 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 it later on. But a read me doesn't really have a standard. There is no kind of convention or like a standard. So they might look very different for different projects. And we'll have a look at some examples just in a bit. 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 purpose. 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 PIPI, 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 vary 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 great. So they just decided to not use any badges at all. It's really just the information and 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 your 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 applies 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 writes Naki comments. Or maybe they will hear about at a conference about your 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 homepage, 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? What does it mean? The failure of 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. And if you want to do that, I think that's a big problem. But there's also more. Read me 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 or read me. For instance, when I clone a project, I'm probably using my favorite editor to just read the text. So it kind of matters that not only the HTML is looking nice, but also that the text itself is good and well-structured. 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 a Mac, maybe, you probably run also something like this. So you want, so that even folks, it 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 expectation from potential users that they find information about the project in those certain ways. So they either try 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 is like, without really like doing it explicitly, people will look for those kinds of things. So I think that's what makes it so important. And this is a thing that happened that was, I think, 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 off 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 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 their hand and welcome them to your project. So it kind of shows that you care about your project, that it's important to interact with your community. In her blog post, she 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 in how to write technical content. But there are people who can help. So I think that's an important thing. 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 writing code. And it's not really that hard 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 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 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 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 do is explain where does the project come from? How does it solve problems? 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 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, oh, wow, 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 explain what your problem does, 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 cookie cutter. The reason being that they couldn't install PyYAML because something broke. Then we tried to use a fork of PyYAML, 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 Poyer library can only read cookie cutter config files. It's compliant with the YAML specification for those kind of structure that we expect in the config, but it doesn't do more. So YAML is actually a subset, sorry. So YAML is, the format says that it's compatible with JSON. So a YAML parser can always import a JSON file. But Poyer can't. What it also can do, it can't write YAML files. 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 parser or something. Like, please don't do it. So that's what I mean with expectations. Point of all, early, so people don't even think about using a project for something they shouldn't do. Pre-requisites I think is also super important. If you want to be sure that people understand that they can't use your software under circumstance 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 a 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 code from a setup py 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 good message, an error message, why it happens. But it would be even better if that was presented on the readme 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 would be even better. Installation. I think there should be one way presented on the readme how you install your project. And in the Python community, that's mostly pip. So cookie cutter is also available via homebrew, via upget, via conda. But there's no point of really presenting that on the readme 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 readme. 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 readme I find. Because there are still people who might not exactly know how you can actually install stuff from the G-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 know 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 your software. But don't list all of them. So you don't want to crawl to pages and pages of awesome features. Just list a couple of them, I find. Maybe seven. Maybe 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 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 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, that's a PyTest 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% 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 whether 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 me in the text editor. So it's important to include the URL to your project. They might just download it from PyPI and then where's the link to the actual repository? Where's the source code? And it's also important to point out 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, GitR 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 support or if I know that it's just a side project or maybe a weekend tag 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 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 are interested? And there should always be a contributor code of conduct. But it 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 I mean, 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 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 the entire read me. So it links to installation documentation, issue tracking. So a couple of things that I mentioned already. But then the next thing that I mentioned 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 really only a couple of slides because I don't want to... Let's just see. So please, please, please, please don't say things like just read the code. Because code is not documentation. But 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 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 things like just read the code. 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 was going through all blog posts of mine and I used all of them multiple times on 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 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 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 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 read me. So kind of as a maintainer, you want to let the people know that you care about this stuff. And if there is a typo in your read me, 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 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 Pythonist 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 have 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 thank you 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 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 code. 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 readme, 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 that. 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 into a journal 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. But if you're supporting Windows and Mac and Linux, probably you 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 comment paste. Yeah. Yeah, I think 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 does all of the things. 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? 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 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 folder layout? So I would link to them. So I think what I usually do is in the, sorry, never mind. So I think at the bottom of my project, I usually have a section that says this project is distributed under the terms of the MIT, distributed as 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 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 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 more questions? Well, we have time. You say that if your documentation has some small type, 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 people fix type on the documentation? Because from my experience, like, oh, this documentation has a type. And then I need to fork the repository, fix the type, then send the pull request, and this is too much in my opinion. Yeah, 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, et cetera. But what you can also do is if in your community section, if you have one, you can, so what we in Cookiecutter say, I think, is every contribution is welcome. So even if it's just a typo, please don't hesitate. Please submit a page. 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 forking, cloning, and all of that stuff, as long as they feel that their work is appreciated and welcome. I know from experience, like, when I first made documentation changes to projects that I didn't feel comfortable enough to make actual code changes, I would submit those documentation patches. But then people 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. 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 white space 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 about like localizing readmifis or things like that? Sorry, can you say the last part again? Are there any projects or things around localizing or internationalizing readmifis or? So I know there are some projects which really make great effort on like translating documentation into different languages. There is one major problem with this, and it's when it gets out of sync, and it 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 they 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 really hard, I think. So what maybe people can do is use simple constructs in English language so that even if you're 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? Nope. Well, then, thanks, Afair. Thank you. Thank you. Thank you. Thank you. Thank you. Thank you. Thank you. Thank you. Thank you. Thank you.
sometimes if I find the time, and I try to write So in June, GitHub released a new project, which What exactly is a read me file? A read me file is read me, or read me TXT maybe. But the name is contact point for users who have problems with it can mean either your project will be actually give you feedback and you will struggle by that is not everyone uses the GitHub web UI, information about the project in those certain So we kind of need to learn about it and get Why are they interested? If they have a problem, with your community. So the first thing that I have an impact. And form a community. I think So explain what your problem does, what your to point out this is not what this project is. message, why it happens. But it would be even your software. But don't list all of them. So you either how you can use the command line this is how it could look like. You explain it want to find out more, please look at the documentation. License. That's a really important actually use your project or not. And as I to know whether the people working on the project open source projects. But sometimes if you don't conduct, it's also important to provide a contact to report something, how can you get in touch? It say things like just read the code. It might be this talk, I kind of wanted to encourage you to, to the official license text, maybe on open request, and this is too much in my opinion. GitHub made it so that you can also edit files on at their hand again. So if they submit a patch