Hi, my name is README! - A Look at Why Docs are So Important
This is a modal window.
The media could not be loaded, either because the server or network failed or because the format is not supported.
Formal Metadata
| Title |
| |
| Title of Series | ||
| Number of Parts | 160 | |
| Author | ||
| License | CC Attribution - NonCommercial - ShareAlike 3.0 Unported: You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal and non-commercial purpose as long as the work is attributed to the author in the manner specified by the author or licensor and the work or content is shared also in adapted form only under the conditions of this | |
| Identifiers | 10.5446/33789 (DOI) | |
| Publisher | ||
| Release Date | ||
| Language |
Content Metadata
| Subject Area | ||
| Genre | ||
| Abstract |
|
EuroPython 201736 / 160
10
14
17
19
21
32
37
39
40
41
43
46
54
57
70
73
85
89
92
95
98
99
102
103
108
113
114
115
119
121
122
130
135
136
141
142
143
146
149
153
157
158
00:00
Event horizonQuicksortReading (process)Self-organizationBitLecture/Conference
00:32
Event horizonSoftware maintenanceCore dumpSoftware developerEmailSoftwareArchaeological field surveyOpen sourceRepository (publishing)Context awarenessBitPattern languageMultiplication signProfil (magazine)InternetworkingGroup actionEndliche ModelltheorieOpen sourceSlide ruleProjective planePresentation of a groupPoint (geometry)BlogArchaeological field surveyDependent and independent variablesServer (computing)Computing platformRepository (publishing)MultilaterationSoftware engineeringLink (knot theory)Core dumpSoftware maintenanceWritingSoftware developerTwitterComputer animation
02:05
Open source1 (number)Formal languageBlogPoint (geometry)Dependent and independent variablesBitOpen sourceType theoryProjective planeMultiplication signDifferent (Kate Ryan album)MereologyReading (process)Inclusion mapService (economics)Web 2.0InternetworkingTelecommunicationNumberRight angleDegree (graph theory)
04:16
InformationBitReading (process)MereologyComputer fileSound effectJSONXML
04:58
Machine codeSoftware testingPrice indexFrustrationElectronic meeting systemHTTP cookieReading (process)Computer fileTouchscreenProjective planeDifferent (Kate Ryan album)Vector potentialMachine codeInheritance (object-oriented programming)EmailInstance (computer science)Repository (publishing)RootManufacturing execution systemComputing platformMarkup languageDirectory serviceHTTP cookieInformationContent (media)Link (knot theory)Software bugFormal languagePoint (geometry)File formatMultiplication signGenderSimilarity (geometry)Object (grammar)Medical imagingMembrane keyboardCuboidStandard deviationBitComputer animationXML
08:43
Reading (process)Projective planeVideo gameRepository (publishing)Open sourceComputing platformHacker (term)Home pagePresentation of a groupComputer animation
09:34
Vector potentialFeedbackWeb 2.0Metropolitan area networkProjective planeReading (process)Expected valueOnline helpInformationText editorDistribution (mathematics)Cross-correlationVector potentialMultiplication signPhysical systemFeedbackVulnerability (computing)Instance (computer science)Logic gateData structureBookmark (World Wide Web)
11:36
WordBinary fileMachine codeScalabilitySoftware developerMultiplication signBitLink (knot theory)BlogProjective planeContext awarenessTwitterWordPatch (Unix)Perturbation theoryContent (media)Natural numberSoftwareMachine codeExistenceSoftware maintenanceComputer animation
13:42
Link (knot theory)BlogGoodness of fitPoint (geometry)Reading (process)Projective planeJSONComputer animation
14:30
RAIDPhysical systemSerial portWindowCondition numberExpected valueError messagePoint (geometry)Product (business)Multiplication signParsingSoftwareComputer fileProjective planeOnline helpParsingMachine codeRight angleInstallation artInformationSoftware maintenanceData structureLatent heatFile formatConfiguration spaceReading (process)BlogLibrary (computing)Computer architectureComputing platformOpen sourceSoftware developerHTTP cookieDatabaseRevision controlDevice driverState of matterRun time (program lifecycle phase)Physical systemGoodness of fitHecke operatorArrow of timeMereologySoftware testingPattern languageDirection (geometry)Set (mathematics)Client (computing)Message passingModal logicPosition operatorFiber bundleSubsetGamma functionXML
19:42
Computing platformCommon Language InfrastructureSerial portInstallation artLink (knot theory)Sheaf (mathematics)Electronic mailing listVector potentialMachine codeHTTP cookieWindowReading (process)Projective planeHTTP cookieLink (knot theory)Computer fileSoftwareInstance (computer science)Block (periodic table)Machine codePoint (geometry)Cartesian coordinate systemSheaf (mathematics)HypermediaRadio-frequency identificationPresentation of a groupConnected spaceFormal languageOpen sourceScripting languageLibrary (computing)Repository (publishing)File systemWeb pageExpected valueNumberSound effectTouchscreenBitInstallation artElectronic mailing listInformationCASE <Informatik>Plug-in (computing)Computer animation
22:46
Open sourceOpen sourceDependent and independent variablesServer (computing)Product (business)Archaeological field survey
23:20
Sheaf (mathematics)FAQMachine codeThermal conductivityCore dumpProjective planeText editorEmailRepository (publishing)InformationStack (abstract data type)TrailFAQSoftware bugMachine codeSoftware maintenanceExtension (kinesiology)BitSheaf (mathematics)Expected valueSet (mathematics)Link (knot theory)Multiplication signTouch typingQuicksortOpen sourceDirection (geometry)Software developerSelf-organizationReading (process)Flow separationInstance (computer science)Interactive televisionArithmetic meanResultantDimensional analysisSource code
26:55
Patch (Unix)Machine codeMultiplication signPatch (Unix)Sheaf (mathematics)Projective planeReverse engineeringSlide ruleElectronic mailing listBlogWordMultiplicationPoint (geometry)Data miningType theoryReading (process)Formal languageBlock (periodic table)Real numberComputer animation
29:20
WritingElectronic program guideProcess (computing)Different (Kate Ryan album)QuicksortMachine codeBlogPoint (geometry)Event horizonIntegrated development environmentLink (knot theory)Software engineeringRight angleDataflowInformationInstance (computer science)System callCoefficient of determinationView (database)
30:50
HTTP cookieProjective planeHTTP cookieTwitterInternetworkingForm (programming)IntegerComputer animation
31:39
InformationLevel (video gaming)Scripting languageWindowDefault (computer science)Point (geometry)Information overloadMereologyReading (process)Lecture/Conference
33:11
Standard deviationLink (knot theory)Computer fileProjective planeReading (process)Lecture/Conference
33:42
WebsiteComputer clusterReading (process)Sheaf (mathematics)Open sourceLink (knot theory)Lattice (group)Projective planeTerm (mathematics)Greatest elementSoftwareLecture/Conference
34:35
Data structureSoftware bugOpen sourceVapor barrierMultiplication signWebsiteLecture/Conference
35:47
Patch (Unix)Set (mathematics)MathematicsCloningMatrix (mathematics)Computer fileForm (programming)Type theoryDirection (geometry)Sheaf (mathematics)Computing platformInstance (computer science)Web 2.0Text editorSpacetimeLine (geometry)Machine codeSoftware maintenanceLecture/Conference
37:44
Instance (computer science)MereologyComputer fileReading (process)CASE <Informatik>Projective planeFrame problemDifferent (Kate Ryan album)Constructor (object-oriented programming)Revision controlFormal languageWordInternetworkingBit rateMachine codeLecture/Conference
Transcript: English(auto-generated)
00:04
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.
00:21
So thank you very much for coming to my talk today. But I also want to thank the organizers and the many volunteers for making this event possible. I think it's really great. So thanks very much. So just a little bit of myself to kind of set a context. My name is Raphael.
00:41
I currently live in Berlin. I lived in Scotland for a while. So I'm still struggling with the weather here in Rimini. I'm a maintainer and core developer of the Cookiecutter project. I also contribute my time to the Pytest project. And sometimes, if I find the time, I try to write blog posts on my personal blog
01:01
at rafael.codes. And during the day, I'm a software engineer at the Movo Group in Berlin. You can find me on the internet using this handle hackerbroad on Twitter and on GitHub. And I'll probably also post the slides, a link to the slides later on my Twitter. So first off, I want to talk a little bit about something
01:23
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
01:42
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.
02:01
And there are also some responses from people from 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.
02:23
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 this talk today. But first, let's look a little bit about the numbers.
02:42
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
03:01
of documentation for both users and contributors. And I can speak from my own experience. When I want to use a project and I struggle to find a license text, I'll just close the tab and move on. Because if I don't know if I can actually use your project, well, what's the point in spending any time looking further?
03:21
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
03:43
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.
04:03
And I struggle a lot to write clear English language maybe in technical documentation. 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
04:21
is a read me file. Then I want to see why is a read me file important at all? Why would you care about it? Then the part in the middle will be about what makes a good read me. So what can you actually do to create better read me files and what effects will that have on your community?
04:41
And then I want to talk 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 this talk and apply that to your own projects. So let's start with the beginning.
05:00
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 it seems kind of obvious. But at the same time, not everyone might be familiar with this concept. Most projects, especially in the Python communities,
05:20
use markdown or restructured text for their read mes, which means you can still read the text, the file contents, just fine if they 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.
05:44
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.
06:01
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 welcoming and so on.
06:23
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 usually when people encounter a problem
06:41
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
07:01
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.
07:22
Yeah, and communities have slightly different purposes for their 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.
07:40
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 PyPI. 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.
08:02
I'm not saying that it's a great example. I'm just trying to highlight right now that those read mes 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.
08:22
And I think that's great. So they just decided to not use any badges at all. It's really just information on the content. So I think that's great. And it's similar for the Django project. So 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
08:41
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
09:01
or on Hacker News maybe and writes snarky comments. Or maybe they will hear about at a conference about their 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.
09:20
So I think it really has a big kind of influence on the adoption of your project. So it could mean either your project will be successful or it could be a failure. But what does it mean? Like what does it mean? Is it a failure if your read me is bad? So I think there is a correlation between those things.
09:42
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
10:00
who's working on the project and no one will tell you what's good or bad. And then lastly, if no one is using your project and no one finds it interesting, no one will ever even consider contributing to your project. So and if you want to do that, I think that's a big problem. But there's also more.
10:21
Read me's can be consumed in very different ways. And what I mean by that is not everyone uses the GitHub web UI, for instance, to read a read me. For instance, when I clone a project, I'm probably using my favorite editor to just read the text. So kind of matters that not only the HTML is looking nice but also that the text itself is good and well-structured.
10:43
Yeah, so that's kind of what I meant. And then there's also another thing. How many of you have run such a command? Like something something and then dash dash help. Or yeah, everyone. Or like if you're using a Linux distribution or a Mac maybe, you probably run also something like this.
11:04
So that invokes, 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.
11:21
So they either try dash dash help or they try to see if there is a man pitch for it. Or they try to look if there is a read me. So I think there's like, without really like doing it explicitly, people will look for those kind of things. So I think that's what makes it so important. And this is the thing that happened
11:42
that was I think at, 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 docs or it didn't happen. And what it means is that if there is no documentation, your project kind of doesn't exist.
12:02
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,
12:21
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.
12:41
But there are people who can help. So I think that's an important thing that not only code contributions are important, but you can also ask for contributions, patches for documentation and your readme. And sometimes that's really hard because it's kind of maybe not our nature
13:02
as software developers to care about these things. So we kind of need to learn about it and get better 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
13:20
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 readme. It needs to be a combined effort
13:40
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 readme and that's based on my opinion. So people might have different understandings but that's what I feel.
14:01
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
14:22
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 readme can do, what a code can't do, is explain where does the project come from?
14:41
What problems does it solve? Why did you start it in the first place? Maybe how did it develop over time? Where does it stand today? And then you kind of want to go into this part, how do you actually install it? How do you use it and where can you go from there? And then for any open source project,
15:01
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
15:22
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
15:41
and now I'm sitting here and it doesn't work. You could have told me that right from the very beginning. So that's what expectations are for. So you explain what your problem does, what 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,
16:02
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 mature your project actually is. So if something is a weekend hack, you should probably point it out on your readme so people don't do stupid stuff
16:21
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
16:41
and we got more and more complaints from users on Windows and also on Ubuntu at some point that they couldn't install a cookie cutter. The reason being that they couldn't install PyYAML because something broke. Then we tried to use a fork of PyYAML, but it also didn't work on other platforms
17:01
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
17:21
that I solved a very, very particular problem that this Puyo 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,
17:40
so YAML is, the format says that it's compatible with JSON. So a YAML parser can always import a JSON file, but Puyo can't. What it also can't 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.
18:02
And I really had to point out this is not what this project is. Please don't use it for anything serious if you want to, I don't know, use your cloud formation and parse that or something. Please don't do it. So that's what I mean with expectations. Point those out early so people don't even think about using a project for something they shouldn't do.
18:23
Prerequisites I think is also super important. You want to be sure that people understand that they can't use your software under certain 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
18:42
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.
19:01
So if your project uses tools or technologies outside of the Python ecosystem, maybe a database driver or a 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.
19:22
So that's code from a setup PY project, sorry, 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, a good message, an error message why it happens. But it would be even better if that was presented on the readme file.
19:42
So without actually using pip install, you would already know that if you're on Windows, it won't work. I think that 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.
20:01
So cookie cutter is also available via Homebrew, via apt-get, 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.
20:22
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
20:41
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
21:03
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 our software. But don't list all of them. So you don't want to crawl to like pages
21:23
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.
21:40
And then you want to have a getting started section. So how can you actually use your project? And that could be either like how you can use the command line interface, but also how do you import your library, maybe. So give an example code and make sure that it actually works. Because again, it's about expectations.
22:01
So if people then just create a script file on the file system, want to run your example code and nothing works, well, you have the same effect kind of that people won't use a project and that's not what you want. So this is how it could look like. You explain it maybe a bit. Yeah, there is, that's a pytest plugin for instance. You say, yeah, there's this cookies fixture.
22:21
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
22:40
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,
23:01
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.
23:22
Troubleshooting. I think there should be an FAQ section in documentation but I wouldn't present it on the readme, 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
23:41
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 readme on the actual repository page, there might be people who read the readme in the text editor. So it's important to include the URL to your project.
24:02
They might just download it from PyPI and then where's, so where's the link to the actual repository? Where's the source code? And it's also important to point out ways of getting in touch with maintainers or other community members. That could be maybe a tag on Stack Overflow,
24:23
that could be an IRC channel, Gitter or any other of those tools. And I think it's also really important to talk a little bit about the community. So who are the people behind the project? I personally find it really interesting to know whether the people working on the project
24:40
are doing that during their working hours or if it's a spare time project. Because for me that to some extent sets also an expectation. So can I expect some sort of, well, support or if I know that it's just a side project or maybe a weekend tag or something, I know that it will probably take a bit more time
25:00
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
25:21
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 you don't have this fine separation of having, yeah, I want to have people who can only do bug triaging
25:43
and they are not allowed to merge to master. So I think it's important to point out how can you actually become a core team member? How do you gain the trust? What do you need to do if you're interested? And there should always be a contributor code of conduct. But it should be there if you really care about it.
26:01
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.
26:23
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 README.
26:41
So it links to installation, documentation, issue tracking. So a couple of things that I mentioned already. But then, the next thing that I mention is the contributor code of conduct. And I think that kind of shows that they care about this. So what shouldn't you do in your README? And this section is really only a couple of slides
27:04
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. And if I have to read your code, if I have to reverse engineer what your project is doing,
27:20
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 way
27:41
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 in blog posts. It's just because you are kind of the creator of the project
28:01
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
28:21
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?
28:43
And I think there are a couple of things that you can do. First of all, I think it's important to encourage any contributors to also submit patches for documentation. And that also involves the readme. So kind of as a maintainer, you want to let the people know that you care about this stuff
29:00
and if there is a typo in your readme, it's not a bad thing to get a patch for fixing a typo. I mean, that's an easy merge. And why wouldn't you want to get this? So don't get angry at them for submitting a patch that only has a typo fix. I think that's great. So it helps make your project more accessible and more welcome.
29:21
And then you can also read or learn more about from other communities. So you, as Pythonist does, you probably know the website readthedocs. And the people behind readthedocs decided that this is an important kind of topic to talk about. And they created the writethedocs community.
29:41
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.
30:00
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 include this link here for you. And then there's also, as I mentioned, the writethedocs community. And in September 10th, I think, there is an event in Prague, for instance, and there are a couple of hundred people, 300,
30:21
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.
30:40
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,
31:01
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 used the cookie cutter project,
31:22
it would be great if you could support it. 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 on Twitter and ask questions there. Thank you.
31:43
Okay, I see a question. Hello, thank you for the great talk. You mentioned that if you have more than one common to install your software, maybe you should have a script around that.
32:02
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,
32:23
even if the user needs to copy and 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.
32:43
Or you have just instructions written down. But my point kind of is, you don't want to overload people with information. Because say you're using Windows, why would I want to hear about how you use Homebrew on Mac OS to install your project? And I think in that, on the readme,
33:01
I think there's no kind of room for this detail, level of detail. So is that an answer to your question? Cool, all right. Hi. If we have a standardized project layout with files like a readme, license,
33:22
contributing, install, and so forth, is it necessary to link those files? Like you have a license and link in readme to license file, or is it just enough to have this standardized folder layout?
33:40
So I would link to them. So I think what I usually do is in the, sorry, so, nah, nevermind. 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,
34:03
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 restructured text as a link, either to the official license text, maybe on opensource.org or somewhere where the official license text is,
34:21
or you can also have a local link so you just link to slash license or something. And I would also always start from the readme. So I wouldn't link from the license to the readme, 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,
34:43
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.
35:01
Okay, any more questions? Well, we have time. You say that if your documentation has some small typos, what happens? Everyone's human.
35:20
It's a very nice bug for people to fix, especially beginners. Do you have any good recommendation to how to lower the barrier for like, people fix typos on their documentation? Because from my experience, like, oh, this documentation has a type, and then I need to fork the repository,
35:41
fix the typo, then send a pull request, and this is like 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.
36:03
But what you can also do is 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 pitch, patch. So just by saying that, I think it encourages people enough to make the effort,
36:22
and they might be even willing to go through the hassle of forking, cloning, and then 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
36:42
to make extra 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, and this is really discouraging, so I think you kind of, as a maintainer,
37:03
you want to take people at their hand again, so if they submit a patch and it fixes a typo, but because their 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
37:22
and remove the white space changes again, so they, and it's important to leave their commit in the history so that they also feel kind of ownership and investment in your projects, so it's just of making it more accessible, more easy, and also that people feel appreciated.
37:42
You were also talking about the fact that some people might not fully understand or read English, for instance. Are there any things that you might know of about localizing readme files or things like that? Sorry, can I say the last part again? Are there any projects or things around localizing or internationalizing readme files or?
38:04
So, I know there are some projects which really make great effort of 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
38:21
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 a 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.
38:42
So, what maybe people can do is use simple constructs in English language so that even if you are not a native speaker, use language that everyone probably understands because after all, as a Python person, you write English words in your code,
39:02
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 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.
39:24
Okay, any other questions? Nope, well, then, thanks Afe. Thank you. Thank you.