Bestand wählen
Merken

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

Zitierlink des Filmsegments
Embed Code

Automatisierte Medienanalyse

Beta
Erkannte Entitäten
Sprachtranskript
thank you very much so the title of my talk today is higher my name is written in the notes some sort of a desperate attempt of myself of getting your attention and I hope it works and I realize it's very early in the morning still kind of after the 1st king out so thank you very much for coming to my talk today the uh but I also want to thank the organisers and the many volunteers for making this event possible thing that's really great so thanks very much so just a little bit of myself to kind
uh set contexts and
monomers Raphael I currently live in the land by lifting Scotland for a while some still struggling with another year in Romania and I'm maintain and co-developer of the
cookie-cutter projects I also contributes far more time to the patterns project and sometimes survive under time and might try to write powerful so my personal blog profiles coats and and during the day and suffer engineer at the removal group and and you can find me on the
Internet using this uh handled Hough abroad on Twitter and get up and probably also post the slides modeling tools slides lateral movement the so 1st of all I want to
talk the bit of little bit about something that happened just recently so in June uh get-out produced and a new project which is called the open source survey and it's a collection ot was a survey across many many repositories with many many people and they found some very interesting things which kind of Help me to kind of make my point was this presentation today so I just want to give some brief insight into what the server was about so 1st of all that had more than 5 so 5 thousand respondents to the survey day um where sourced from almost 1000 open source repositories and get alone and there are also some responses from people from using other platforms and 1 of the
biggest inside actually which was very very prominent prominently displayed on the web so that electron was that documentation is highly valued but often overlooked and there were like a couple of follow up post and on the Internet people saying why a this is people tried to understand like why exactly don't we cares about documentation or 1 of the problems that we are facing and I find this really interesting some because it kind of brings me to why I'm giving us talk today
but 1st let's look at it in a little bit about the numbers so 1st of all um 93 of all of the that response said that incomplete or all documentation is a real problem and I will certainly agree that some the next 1 is really interesting for open source project well licenses are by far from the most important type of documentation for both users and contributors and I can speak from my own experience when I want to use a project and I struggle to find the license texts just close and move on because if I don't know if I can actually use your projects well what's the point in spending time with her father from but also documentation have strayed Inclusive Communities and so if you target a very specific problem you might they have a different kind of read me then if you are maybe targeting a broad audience but it's generally a good idea to kind of welcome people explain what you're doing and make it as inconclusive us as you possibly can and then there is also another thing nearly a quarter of the open source community and reads and writes English less than very well I didn't take part in the service I don't know exactly what the question was but uh I'm not a native english speaker and I struggle a lot too right clear um English language maybe and technical documentation from but so I can use to some degree I understand why people would say that's a guess so
what's the agenda for today 1st of all I want to talk with you about what exactly is a readme file then I wanted them to see why is a readme file important at all why would you care about it then the part in the middle will be about what makes a good read me so what can you actually do to trade better readme files and what effects will that have on your community and then I want to talk about it just a little bit about things that you definitely don't want to have a married file and as a takeaway later on I want to give you some advice from them where to look for more information and how we can take the learning from the distort and applied it to your own projects so let's start with the beginning
what exactly is a readme file readme file is
many things but it's 1st of all it's a text file and this is your coat in your repository and it seems kind of obvious but at the same time I'm not everyone might be familiar with this concept most projects especially in the Python communities is marked on a restructured text for their it means which means you can still read the and the text the file contents just find that therefore wanted nicely but platforms like attempted love whatever and they will render your them actual text file and generated HTML from that so the books by certain and you can include images and what the so that's how you would usually expect a project to be looking like so you have a root directory and then somewhere there will be some fire called readme artist you read Mandy or just read mean more readme txt membrane but the name was always kind of what you would expect but we use more it's also what makes your project's 1st impression and that's why it's super important um super-important because it makes it makes a big difference if people actually use your project it's wrong or not and so the adoption of closely related to how well you read me structured and what commands and so on it's also the 1st contact point for users who have problems with the software and and I know from experience and to cookie-cutter project is quite popular um and we get a lot of them because by people reporting box and what not and like usually when people encounter a problem with your code about maybe and they will not be in their happiest mood so I find it quite important to kind of take them by the hands on you read me and tell them what they can do about that problem problem and them use language that doesn't kind of make them even more aggressive Mary so it should be kind of understanding but also straight to the point where can I find information but look at the later on but the readme doesn't really have a standard there's no kind of convention or like it's a standard here so they might look very different for different projects and we'll have a look at some examples just innovates um yeah and communities have slightly different purposes for the admittance but at the end of the day reading always has a assigned kind of same kind of purpose it it tells a story and it tries to get people interested in your project so just looking at some examples because they really vary quite a bit so for the cookie cutter project you will find there is a header and you find edges for the bill status the court coverage of of the link to PI PI um and then a local for instance and then it goes on with features and example Croats and and then more detailed information about the way you can find more information I'm not saying that is a great example I'm just trying to highlight right now that that sweetness that vary quite a bit so looking at the flask projects which interestingly enough doesn't use any markup format it's just the cheeks you but still it's a very very good read me because it contains all the information that a potential user needs and and I think that's that's great so they just decided to not use any badges at all it's really just information on the content so I think that's great and it's similar for the Django project so gender is a massive project but the readme file it serves it nearly fits on 1 screen so you will also find all the information that you need to learn more about objects so why is it so important 1
speaking yesterday In my opinion you only get 1 chance to make a 1st impression that applies to many things in life maybe but it also implies the open source projects because from my experience usually people find a project maybe someone poses on reddit score on Hacker News maybe and write snarky comments or maybe they all hear about at a conference about the projects so the 1st thing that they usually do would go to your repository and just because the platforms work that way they will presenter read me as your homepage fuel so I think it really them as a big kind of influence on the adoption of your projects so it can mean either your project
will be successful and or could
be a failure but what does that mean like
what does it mean that the failure of read is bad and so I think there is a correlation between those things so 1st if you fail to appeal to potential users they won't be interested and want to use the project and your kind of story ends there already but then if you don't get any user project no 1 will actually give you feedback and you will struggle to really improve your project over time because you're the only 1 who's working on the project and no 1 will tell you what's good about and then lastly them if no 1 is using a project and no 1 finds it interesting no 1 will ever been was considered contributing to a project so and if you if you want to do that I think that's a big problem but there's also more their weakness can be consumed in very different ways and what I mean by that is not everyone uses the gates of what you I for instance to read read me and France's when I call a project on probably using my favorite is what to just read the text so kind of matter said not only the 2 miles looking nice but also that the text itself is good and what structure yeah that's so that's kind of what I meant some and then there's also saying how many of you have run such a command like something something and then Dutch Dutch help or everyone had or it like if you are using Linux distribution or or a Mac maybe you probably ran also something like this so you want so that in books it displays a manual page for you and the most operating systems and what I'm trying to say with this is that there is kind of this this expectation for from potential users that they find information about the project in those certain way so that you tried gestures help or they try to see there is a man page for it or they try to look at there's read me so I think there's like without really like doing it explicitly people will look for those kind of things I think that's that's what makes it
so important but and then this is the thing that happened so that was the thing that's uh so there is a technical writer she's called Mikey aerial and she posted a blog posts 2 years ago I think she started this Twitter hashtag kind of of stocks or it didn't happen and what it means is that if there is no documentation your project kind of doesn't exist so you you need to document things that are important to tell users because it's more than just providing context it's also about kind of taking people by their by the hand and welcome them to your project and show so it kind of this shows that you care about your project and it's important to interact with the community and in her blog post you also said
that you're not long words are work and I would certainly be that Siemens software developer of so I'm I'm not technically that really educated and how to write technical content but there are people can help so I think that's an important thing that's uh not only called contributions are important but you can also ask for contributions from patches for documentation and you read me and sometimes that's really hot um because it's kind of maybe not our nature as tougher developers to care about these things come so we kind of need to learn about it and get better at it just this just as a writing coach and it's it's it's not really that hard if he if you kind of invest a bit of time in reading from people who actually know how to do that and also maybe watch some conference talks on those and communities so the main thing to remember from my blog post was that's and all these efforts need to be collaborative out so it needs to be an effort from the community it can't be just to maintain our some kind of looking after the reading it needs to be a combined effort and it needs to be simple and scalable if you are interested that's link to
them come to about but I'll post electrons off so let's talk
about what makes a good read me and that's based on my opinion so people might have different understandings but but that's what I
feel and all of these points the most important thing for me is empathy so you as the creator of a project as a maintain on you need to think about why people come to your projects why are they interested um if they have a problem it's important to kind of have this understanding for them off not being smart you're making stupid jokes or or them all of these things so I think it's important to use empathy and and how you communicate with their community so the 1st thing that I find important to
tell a story so what we can do what a code can do is explain where does the project come from what problems doesn't solve why did you started in the 1st place maybe how they did it develop over time where does it stand today um and then you can I want to go into this part how do you actually and so that's how to use it and where can you go from there and then for any open source product it's really important to also invite people to contribute to the project and help change the maybe in the course of the project the direction have an impact from and form a community think that's important and then in the 2nd most important thing I think is set expectations so maybe you've done that you found this blog post and then people say just run I don't know just 1 to install or whatever and then you get this arrow saying well this doesn't work on Windows and you're like wow that's that's nice so I just spent like maybe a couple of installing the stuff and I invested my time and non sitting here and it doesn't work you could have told me that right from the very beginning so that's what expectations for so he explained what the problem that's what from a problem sorry what a project us what the problems it solves and then you can also point them to other projects because if years amounting get those questions all over again I want to do this your project does something similar maybe but it's not quite so maybe have some information what other projects you might want to look at and then you can also let your users know how much Europe project pictures so if something is a weak heck you should probably pondered out on a readme so people don't do stupid stuff and run that stuff and production the next day after so it's important to kind of states somewhere and what's the development status and this is actually a lesson that i loans that In the cookie-cutter project used young them as a configuration for and we get more and more complaints from users on Windows and also from the underwent at some point that they couldn't install a cookie cutter the reason being that they couldn't stop I young because something broke them then we tried to use a fork of primal wrongly on but also didn't work on other platforms and on other architectures so I was so frustrated at some point it I wrote my own Yamal parser and I knew that I will never implement the full specification because to to be honest it's way too complex to write right any parser for it and have no idea of the black to do that but I am but I'm trying to say here that I solve the very very particular problem that this point a library can only read cookie-cutter config fast is compliant with the gamma specification for those kind of structure that we expect in the conflict but it doesn't to more so young is actually a subset of sorry um it's not so young was this of as it is compatible Jason so Yamal parser can always imported Jason um but for you can't and what it also can do it can write down files so and people get really confused and they will start thinking of they should maybe use it for I don't know super important projects and I really had to point out this is not what this project is please don't use it for anything serious this if you want to go out all use your formation and positive something like please don't do it and so that's what I mean is expectations bundles of leaves so people don't even think about using a project for something should do prerequisites think is also super important you want to be sure that people understand that they can't use your software under circumstances and conditions so if Europe suffers only test that's maybe it's technically working on Windows but you've never tried you might put 1 to point that out so people don't have this super frustrating situation in which they just 1 and 2 in our the python versions them there are more and more projects were only patterns the compliance so you should find that out so people don't try to inside and Python to or vise versa like couple of years back and also dependencies so if you project uses tools are technologies outside of the Python ecosystem maybe a database driver clients whatever and maybe you should let them also they don't so your project wonder why it doesn't work and let them know that they need to install something on the system 1st uses so that's that's the 1 code from a set of QI project necessary from a set up you are far from apart projects and so they check for the platform and then raise alarm tomorrow and I think it's good because they give they give a good message an error message why it happens a lot it would be even better if that was presented on the readme file so without xt using
Pippin style you already know that if you're on windows it won't work I think that's that's would be even better installation
I think there should be 1 way presented on the read million start a project and in the Python community that's mostly pet so cookie-cutter
is also available via homebrew via AP gets the outcome but there's no point of representing that on the readme if there is to an the main kind of insulation method is that have so you can have the other methods in your documentation but just not on the readings so should become size and only 1 month and and then you also as I mentioned you want to link to media and sections of your documentation that as um so it could be just this 1 cannot of command pit instead of something and and that's all you need but it should be presented on the reader can find them because there are still people who might not that in all hurry connections to other stuff from from the she so so please presenters much have for other languages there might be a goal gaps for instance so them just assume command I think is important to to know what what happened and make it as easy as possible so you're kind of installation requires multiple steps maybe have a script in Europe from the repository and the script does all of the work them but users only need to run this 1 script to make it easy and now features you also want to talk about features because that's ultimately what gets users interested in using software but don't this all of them so you don't want to spare the crawled from like MIT pages and pages of all some features and just list a couple of them defined and maybe maybe 7 maybe that's that's a good number of them and depending on how you presented I think that's kind of as long as you get it on 1 screen applicants scandalous and you want to have a getting started section so how can you actually use your projects them and that could be either like how you can use the command line interface but also hold the import your library maybe some so given example code and make sure that it actually works uh because again it's about expectations so if people than just create a script file on the file system want to run you example code and nothing works so well you have the same effect kind of that people want use of projects and that's not what you want so this is how it could look like he explained it maybe a bit yeah there's that's the practice block and for instance you say yeah there's this cookies fixture and then you show the colony explained you can do this and this and if you want to find out more please look at the documentation license them that's a really important topic for any open source project because if your project doesn't have a license file uh you kind of don't allow people to actually use your project so it's important to point this out and link to the full license text
and that's the data from the ticket of open source server and 64 per cent of the respondents said that an open source license is very important and decides of whether people actually use a product amount and as I mentioned before that also I had the same experience and 67 per cent also said that it's what decides whether they want to contribute so the license might not be the 1 that day and usually use or that you comfortable as they might have contributed our just because of a license troubleshooting
I think there should be an FAQ section and documentation but I wouldn't be presented on the reading I think so I would read a link to it I think that would be a nice way of doing that but it's important to have a dedicated troubleshooting section so if if people active problems they know where to look and where to find this information please also have a link to your issue tracker like even if the project exists all this get top and people mostly read carried me on convection repository approach there might be people who read the readme ended in the text torso so it's important to include to your out projects they might just downloaded from PI PI and then where's so where's the link to the X repository rest source code it is also important to point out way like ways of getting in touch with maintenance or other community members that could be maybe uh tag on StackOverflow that could be an Irish Sea channel picture of any of those and tools from anything it's also really important to talk a little bit about the community and so were the people behind the project I personally find it really interesting to know whether the people working on the project are doing that during their working hours or if it's a spare time project because for me that to some extent sets also on expectations so can I expect some sort of them well supports or if I know that it's just a side project at from idea we can tackle something on all that it will probably take a bit more time for them to respond to any issues that might have and also how can it contribute to your project and how to become a core team member in give how this like it's moving towards direction of making it better for open source projects but sometimes with if you don't have to have an organization for a project for instance it's hard to invite people to your core development team so as of right now I think you can and grant commits so write access to your repository but but you don't have this find and separation of having yeah I want to have people who can only do bark triaging and they are not allowed to merge 2 master or so I think it's important to point out how can you actually become a core remember how do you gain the trust what you need to do if you're interested in and this should always be a contributor code of conduct but it should be should be there if you really care about it and that it shouldn't be just like yeah people talk about the stuff uh it's what you do nowadays but I mean it's it has and it has a meaning so if you're not familiar with that it kind of gives a guideline on how you interact with your community things that you shouldn't do and if you if you misbehave kind of what happens on um so the user and contributor code of conduct it's also important to provide a contact information of if something happens if you want to report something how can it and touch it could be an e-mail or something else and just an example from that the project so that's their entirety results that links to installation documentation that issue tracking so a couple things that I mentioned already but then the next thing that dimension as the country a code of conduct and I think that kind of shows that they care about is so what shouldn't you do
in your reading and this section is is really only a couple of slides
because I don't want to and know that's that's a C like so please please please please don't say things like just read the code because code is not documentation and if I have to read your code if I have to reverse engineer what a project is doing I'm not using a project I thing that's that's very it says a lot about whole much actually care about the people that want to use project so please don't say a thing like just read the code York yeah it might be an inflated you or something but I I mean your code won't ever be this good that people can use it in the same they they would use a beginner's tutorial for a projected onto the also try to avoid words like easy the obviously and just and I like I was going through all blog post of mine and to use all of them multiple times and block posts it's just because you are kind of the creator of the project and you want to promote it as being easy you want to say yeah this this API so also met so obvious what you need to do but there might always be people who don't find it obvious that it might not find it easy to use they might be very new to Python or any other language so by using those words you the kind of make them feel like they're stupid and that makes some them unwelcome some so don't do that and the list goes on and but for this talk I decided to just leave it at that then goes on the most important points um and but also don't want to discourage you from actually caring about the stuff that so what can you do to improve your own
projects nothing there are a couple of things that can do
1st of all I think it's important to encourage any contributors to also submit patches for documentation and that also involves the real thing so kind of as maintained you want to tap let the people know that you care about stuff and if there is a type when you read me it's not a bad thing to get a patch for fixing the title I I mean that's an easy merchants why wouldn't you want to get so don't get angry at them for submitting a patch that only has a type of fixed I think that's that's great so it helps make your project more accessible and more welcome and then you can
also read what all and more about from other communities and so you this path this does you probably know the website greet the docks and just the people behind the read the dogs decided that this is an important for um kind of topic to talk about them and they created the writer docs community and wearing a T-shirt and I have stickers that further and so they they have this this guide kind of for how can you get started was writing documentation them and there is it's not a lot of information but I think that's all you need to really to get started and then there's also a couple flow posts so for instance this 1 talks about the story telling aspect of it that you want to explain to users we're coming from where you're going and so I'll include thank you for you and then there's also as I
mentioned the right ducks community and in September 10th I think there is an event in in Proc for instance and there are a couple of hundred people 382 and talk of all of these things and they come from very different kind of back from some of the software engineers there might be technical writer so that's the kind of full-time job to care about this them there might be some customer success engineer so people care about that your customers can actually use your call and there might be support people there might be all sorts of different people and the thing that creates a very nice environment and a different points of view which is always important for this and empathy kind of thing that I talked about earlier so with this talk I kind of
wanted to encourage you to as Python engineers to care about documentation and especially about the readme because that's the most important document a thing in the whole project and
with that I have some stickers if you're interested in um that uh yes so I have subsequence of
interest and then I as a personal note I just wanted to mention this very briefly and so if you may be used to cookie-cutter projects and it would be great if you could support it and if we can talk about later on I just want to leave it here for the
and so that's me on the Internet's if you have any questions I'm happy to take questions now later on or you can uh form integer and ask questions but few
be on mission and at the well thank you for the great told you mention that if you have more than 1 common to style itself maybe should have a script of that kept were if you spot in Windows and Mac and Linux each have more than 1 scripts because like best isn't walkin windows by default only which have like 0 this is following this is from that and that's going back to have just 1 comment this is not preferred use have all the commons even if you use each copy and paste there yeah I think that's a that's a valid point so my kind of why said that this because you wanted to make it as easy as possible so you could also have a separate document that says installation or something that could be an executable script which made it does all of the things I have them or you are you have just instructions written down there but my point kind of this you don't want to overlook people with information because say you're using Windows why would I want to hear about how you use homebrew on my questions a project and I think in that's on the reading I think there's no kind of room for this detailed level of due on the so is a an answer to your question called part yeah hi you we have a standardized so logically out uh read flies like a readme license contributing in style and so for the is it necessary tool in those files like co you have a license and lean in read me license file or is it just enough to have the standardized of Boulder Leo um so so I want to link to them um so I think what I usually do is and the and some so it
but sorry so now want so I
think like at the bottom of my project are usually some have a section that says and this project is distributed under the terms of the MIT lattice distributed as open free and open source software distributed under the terms of the MIT license then the MIT licensing this because I use reStructuredText is a link them either to the official license text maybe on open source of Oracle somewhere where the official license sexes or you can also have low local link that so you just link to slash license or something and and I would also like always start from the read me so I Wendling from the license to the readme but the other way around them
and the reason why I would do that is because if you kind of want only to rely on the structure people actually need to be experienced are familiar with this kind of structure so again if you make it more explicit will be accessible to everyone even if they are completely new to you the typical structure of open source projects so this this again it any more questions I won't we have time so what we say that but if you up that mentation has some small time what happens the evidence for the human how it so the nice well but for people to free special begins that hot do you have any good recommendation to hold to lower the barrier for like people fixed by presume that the plantation because fomites rooms like a locus differentation has applied and then I need to fault was sorry could fix the pipe will then send the police and the site too much my opinion here that's that's fair enough from so if I'm not mistaken could have made it so that you can also edit files on the web platforms so something that's it step into the right direction so it's easier for people without even having to use a command-line set from them but what you can also do this if you in your community section if you have 1 you can come so what we in cookie-cutter say I think is every contribution is welcome so even if it's just a typo um please don't hesitate please submit pitch patch just by saying that I think it encourages people enough to make the effort and they might be willing to go through the hassle of cloning forking cloning and all of that stuff as long as they feel that their work is appreciated and welcomed uh I know from experience like when I 1st met documentation changes to projects that I know didn't feel comfortable enough to make of cold changes I would submit both documentation patches but then people 7 said to me this needs to work with this tool that magically validates that all documentation is working and you need to do this and this and this and this is really discouraging so I think you kind of as a mentality you want to take people at their hand again so it's a submit a pension matrix is a type form but because they're editor for instance strips all of the white space and is maintaining a you might say I don't want to have all of these changes all of those lines but only this type of maybe you as an antenna can you can kind of do their works and removed the wise prestigious again so they and it's important to leave their comments in the history so that they also feel kind of ownership and investment in your so just of making it more accessible more easy and also the people feel appreciated and you were also and talking about the fact that some people might not fully understand or read English frames and there are there any things that you might know of about battle creating we fight and things like that I'm sorry case last pouring that other EU project of things around the localizing are internationalising comedy Pfizer so I know there are some projects which really make rate of 4 of the Internet on on like con translating documentation in 2 different languages there is 1 major problem with this and when it's gets out of sync and that happens quite easily if you have multiple copies of the documentation that kind of brings us back to this whole um I have this problem and then you ask them antenna tell you well just look at the documentation is say I'm using the Chinese version of the documentation and I just copy-paste the codon and so it's it's really hard I think and so what who maybe people can do is use use simple constructs in English language so that even if you're not a native speaker use of everyone probably understand because after all as a Python person you write English words in your code so you might already have basic understanding of the language from the and on that note you shouldn't do stupid jokes in your documentation and because those are always like really hard for people who are not native speakers to understand it so I think that's what I learned over the years of yeah yeah OK and any other questions the know what then sense of very
Bit
Selbst organisierendes System
Ereignishorizont
Quick-Sort
Computeranimation
Software
Softwareentwickler
Decodierung
Web log
Affine Varietät
Mustersprache
Gruppenkeim
Profil <Aerodynamik>
Projektive Ebene
Ereignishorizont
Computeranimation
Bit
Punkt
Sondierung
Dokumentenserver
Dokumentenserver
Open Source
Sondierung
Kombinatorische Gruppentheorie
Systemplattform
Computeranimation
Internetworking
Rechenschieber
Open Source
Informationsmodellierung
Endogene Variable
Server
Projektive Ebene
Telekommunikation
Subtraktion
Bit
Punkt
Affine Varietät
Open Source
Formale Sprache
Zahlenbereich
Computeranimation
Internetworking
Open Source
Benutzerbeteiligung
Dienst <Informatik>
Minimalgrad
Rechter Winkel
Datentyp
Endogene Variable
Mereologie
Projektive Ebene
Inklusion <Mathematik>
Lesen <Datenverarbeitung>
Soundverarbeitung
Bit
Affine Varietät
Mereologie
Information
Elektronische Publikation
Computeranimation
Lesen <Datenverarbeitung>
Vektorpotenzial
Maschinencode
Subtraktion
Bit
Punkt
Quader
Beschreibungssprache
Formale Sprache
Systemplattform
Ähnlichkeitsgeometrie
Computeranimation
RFID
Softwaretest
Konstante
Maschinencode
Vererbungshierarchie
Punkt
Wurzel <Mathematik>
Inhalt <Mathematik>
E-Mail
Bildgebendes Verfahren
Touchscreen
Affine Varietät
Dokumentenserver
Folientastatur
Cookie <Internet>
Indexberechnung
Ähnlichkeitsgeometrie
Elektronische Publikation
Binder <Informatik>
Objekt <Kategorie>
Geschlecht <Mathematik>
Cookie <Internet>
Dateiformat
Projektive Ebene
Information
Verzeichnisdienst
Standardabweichung
Lesen <Datenverarbeitung>
Instantiierung
Videospiel
Dokumentenserver
Affine Varietät
Open Source
Projektive Ebene
Hacker
Kombinatorische Gruppentheorie
Systemplattform
Computeranimation
Homepage
Distributionstheorie
Rückkopplung
Vektorpotenzial
Vektorpotenzial
Physikalisches System
Computeranimation
Erwartungswert
Verknüpfungsglied
Lesezeichen <Internet>
Rückkopplung
Softwareschwachstelle
Projektive Ebene
Information
Datenstruktur
Korrelationsfunktion
Hilfesystem
Lesen <Datenverarbeitung>
Instantiierung
Binärdaten
Bit
Web log
Wort <Informatik>
Natürliche Zahl
Skalierbarkeit
Störungstheorie
Kontextbezogenes System
Binder <Informatik>
Computeranimation
Patch <Software>
Twitter <Softwareplattform>
Maschinencode
Projektive Ebene
Wort <Informatik>
Inhalt <Mathematik>
Compiler
Softwareentwickler
Punkt
Affine Varietät
Projektive Ebene
Computeranimation
Lesen <Datenverarbeitung>
Punkt
Web log
Versionsverwaltung
Computeranimation
Richtung
Client
Mustersprache
Bildschirmfenster
Punkt
Umwandlungsenthalpie
Softwaretest
Datenhaltung
Güte der Anpassung
Biprodukt
Teilmenge
Menge
Rechter Winkel
Konditionszahl
Dateiformat
Projektive Ebene
Information
Gammafunktion
Versionsverwaltung
Faserbündel
Message-Passing
Fehlermeldung
Aggregatzustand
Maschinencode
Ortsoperator
Hecke-Operator
Systemplattform
CLI
Physikalisches System
Erwartungswert
Software
Programmbibliothek
Zeitrichtung
Datenstruktur
Softwareentwickler
Konfigurationsraum
Hilfesystem
Affine Varietät
Open Source
Physikalisches System
Elektronische Publikation
Parser
Modallogik
Druckertreiber
Mereologie
Cookie <Internet>
Computerarchitektur
Bit
Maschinencode
Punkt
Formale Sprache
Zahlenbereich
Kartesische Koordinaten
Kombinatorische Gruppentheorie
Computeranimation
Homepage
Mailing-Liste
Erwartungswert
Software
RFID
Maschinencode
Programmbibliothek
Skript <Programm>
Dateiverwaltung
Touchscreen
Soundverarbeitung
Einfach zusammenhängender Raum
Affine Varietät
Dokumentenserver
Open Source
Cookie <Internet>
Vektorpotenzial
p-Block
Binder <Informatik>
Elektronische Publikation
Verschlingung
Hypermedia
Cookie <Internet>
Garbentheorie
Projektive Ebene
Instantiierung
Lesen <Datenverarbeitung>
Resultante
Maschinenschreiben
Maschinencode
Bit
Selbst organisierendes System
Hausdorff-Dimension
Computeranimation
Richtung
Open Source
Weg <Topologie>
Erwartungswert
Maschinensprache
Endogene Variable
FAQ
Softwareentwickler
Maßerweiterung
E-Mail
Trennungsaxiom
Affine Varietät
Dokumentenserver
Open Source
Quellcode
Binder <Informatik>
Biprodukt
Quick-Sort
Softwarewartung
Arithmetisches Mittel
Garbentheorie
Menge
Chatten <Kommunikation>
FAQ
Server
Garbentheorie
Speicherabzug
Projektive Ebene
Information
Wärmeleitfähigkeit
Lesen <Datenverarbeitung>
Instantiierung
Maschinencode
Punkt
Web log
Formale Sprache
Mailing-Liste
p-Block
Computeranimation
Data Mining
Rechenschieber
Multiplikation
Reverse Engineering
Garbentheorie
Projektive Ebene
Wort <Informatik>
Lesen <Datenverarbeitung>
Patch <Software>
Affine Varietät
Reelle Zahl
Datentyp
Projektive Ebene
Computeranimation
Sichtbarkeitsverfahren
Subtraktion
Punkt
Sichtenkonzept
Systemaufruf
Datenfluss
Quick-Sort
Ereignishorizont
Computeranimation
Rechter Winkel
Prozess <Informatik>
Information
Elektronischer Programmführer
Programmierumgebung
Software Engineering
Instantiierung
Zustandsdichte
Affine Varietät
Computeranimation
RFID
Punkt
Elektronische Publikation
Computeranimation
Internetworking
Bildschirmmaske
Ganze Zahl
Bildschirmfenster
Mereologie
Skript <Programm>
Projektive Ebene
Information
Default
Lesen <Datenverarbeitung>
Verbandstheorie
Software
Open Source
Minimum
Projektive Ebene
Garbentheorie
Binder <Informatik>
Term
Benutzerführung
Computeranimation
Lesen <Datenverarbeitung>
Matrizenrechnung
Web Site
Maschinencode
Rahmenproblem
Mathematisierung
Formale Sprache
Versionsverwaltung
Systemplattform
Raum-Zeit
Computeranimation
Richtung
Internetworking
Benutzerbeteiligung
Bildschirmmaske
Datentyp
Datenstruktur
Gerade
Feuchteleitung
Konstruktor <Informatik>
Affine Varietät
Open Source
Bitrate
Elektronische Publikation
Texteditor
Patch <Software>
Menge
Wort <Informatik>
Garbentheorie
Projektive Ebene
Instantiierung
Klon <Mathematik>

Metadaten

Formale Metadaten

Titel Hi, my name is README! - A Look at Why Docs are So Important
Serientitel EuroPython 2017
Autor Pierzina, Raphael
Lizenz CC-Namensnennung - keine kommerzielle Nutzung - Weitergabe unter gleichen Bedingungen 3.0 Unported:
Sie dürfen das Werk bzw. den Inhalt zu jedem legalen und nicht-kommerziellen Zweck nutzen, verändern und in unveränderter oder veränderter Form vervielfältigen, verbreiten und öffentlich zugänglich machen, sofern Sie den Namen des Autors/Rechteinhabers in der von ihm festgelegten Weise nennen und das Werk bzw. diesen Inhalt auch in veränderter Form nur unter den Bedingungen dieser Lizenz weitergeben
DOI 10.5446/33789
Herausgeber EuroPython
Erscheinungsjahr 2017
Sprache Englisch

Inhaltliche Metadaten

Fachgebiet Informatik
Abstract Hi, my name is README! - A Look at Why Docs are So Important [EuroPython 2017 - Talk - 2017-07-12 - PyCharm Room] [Rimini, Italy] When starting a new project, as developers we usually get right into hacking things, like tinkering with libs that we would like to learn or solving a particular problem as quickly a possible. Occasionally we also decide to publish the resulting package to PyPI, so that others can use our nifty code, submit a pull request and maybe even form a community around the project. If you're lucky someone might find it on the front-page of PyPI or the GitHub search or maybe even Hacker News or Reddit. What happens next is on you really. But what does that mean? Before jumping right to the command line and installing your package, those who are interested usually try to find out what problems the project is solving and how it can help them with their own. That's what your README file is for - it's most likely the first thing potential users read, that you control. A good README briefly and concisely explains what your software does, how it can be installed and what API it exposes. You also want to provide information on the requirements, the license it uses and how the project is managed. Who are you? How to get in touch to report problems and give feedback? Where can I find the Code of Conduct for this project? This talk is for everyone who is interested in working on open source projects and wants to know how documentation can help newcomers and more experienced users use your code and to encourage them to engage in the community

Ähnliche Filme

Loading...
Feedback