Making an awesome Open-Source Project
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 | 110 | |
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/51135 (DOI) | |
Publisher | ||
Release Date | ||
Language |
Content Metadata
Subject Area | ||
Genre | ||
Abstract |
|
00:00
Software developerCodeWritingShared memoryOpen sourceRight angleCodeComputer animation
00:52
Software developerCodeTwitterOpen sourceAreaForm (programming)Right angleSoftware developerBitProduct (business)Type theoryQuicksortUniqueness quantificationProcess (computing)CodeData managementWeb-DesignerCartesian coordinate systemDirection (geometry)Bridging (networking)Domain nameSoftwareMusical ensembleWritingVideo gameMachine visionWeb 2.0Computer animation
04:21
Software developerGeometryOpen sourceRight angleLibrary (computing)Structural loadAutomatic differentiationProduct (business)InternetworkingTerm (mathematics)InformationField (computer science)Cartesian coordinate systemAreaCodeSource codeComputer animation
05:54
Open sourceSoftware frameworkWritingSoftware developerMereologyLibrary (computing)Different (Kate Ryan album)Computer programmingNumberCodeDecision theoryInjektivitätCore dumpSocial classVideoconferencingRight angleView (database)Line (geometry)Perspective (visual)Multiplication signComputer animation
09:36
Software developerCodeUser interfaceWeb pageSource codeLibrary (computing)Multiplication signDesign of experimentsRandomizationSoftware developerPropositional formulaGoogolRight angleDescriptive statisticsProcess (computing)Data managementDialectOpen sourceRoyal NavyComputer animation
10:58
Software developerPort scannerGroup actionLanding pageLibrary (computing)Installation artMachine codeWeightGoodness of fitSampling (statistics)Computer fileSystem callDatabaseGroup actionLanding pageWebsiteJava appletMultiplication signOpen sourceCodecMobile appData managementBinary codeWeb pageLine (geometry)Existential quantificationNumber2 (number)Link (knot theory)Demo (music)Video gameData storage deviceCodeRight angleProcess (computing)Cartesian coordinate systemInheritance (object-oriented programming)Software developerFunctional (mathematics)Near-ringPoint (geometry)Coma BerenicesCone penetration testSelf-organizationComputer animation
15:41
Image resolutionRotationStandard deviationSoftware developerCodeComputer fileSynchronizationHost Identity ProtocolBookmark (World Wide Web)Computer iconArithmetic meanLocal ringVideo gameIcosahedronRankingCloud computingFingerprintLine (geometry)Execution unitInclusion mapWeb pageMenu (computing)Library (computing)Landing pageDefault (computer science)Revision controlWebsiteContent (media)Descriptive statisticsWeb pageMedical imagingCodeFile formatCASE <Informatik>Branch (computer science)Software repositorySampling (statistics)System administratorProduct (business)Formal languageReading (process)Electronic mailing listTraffic reportingProcess (computing)Right angleComputer animation
18:08
CurvatureExecution unitLocal ringWeb pageBookmark (World Wide Web)Tracing (software)Server (computing)Decision tree learningSoftware developerVirtual machineSynchronizationDiscrete element methodClient (computing)SummierbarkeitGroup actionInstallation artDean numberCodeWeightSoftware frameworkGraphical user interfaceContrast (vision)Expert systemPhysical systemType theoryEmailVisual systemWeb browserDemo (music)CodeDomain nameWeb pageWeightBranch (computer science)TrailMultilaterationSampling (statistics)Template (C++)Type theoryDomain nameLink (knot theory)SynchronizationBookmark (World Wide Web)Computer fileProgrammer (hardware)Installation artContent (media)InformationUniform resource locatorInheritance (object-oriented programming)RootReading (process)AreaRight angleCore dumpApproximationGoodness of fitLevel (video gaming)Library (computing)Computer programmingFigurate numberMultiplication signRadical (chemistry)Computer animation
22:04
Software developerLibrary (computing)Web pageCodeRight angleMultiplication signDisk read-and-write headCartesian coordinate systemSampling (statistics)Computer animation
23:53
Software developerCodeVisualization (computer graphics)Online helpC sharpDifferent (Kate Ryan album)Computer fileBuildingSet (mathematics)Multiplication signLibrary (computing)Right angleParameter (computer programming)Social classSubject indexingComputer animation
25:26
Software developerPoint (geometry)Software developerSineTwitterRight angleWater vaporHacker (term)Software bugFormal languageCollaborationismCodeBuildingExpected valueElectronic mailing listMereologyVirtual machineMessage passingDependent and independent variablesLibrary (computing)Form (programming)AuthorizationSoftwareLine (geometry)EmailSoftware maintenanceBlogCASE <Informatik>WordOnline helpGoogolInformation1 (number)Descriptive statisticsProcess (computing)WritingVideo gameNeuroinformatikTrailComputer animation
31:48
Software developerError messageMessage passingMereologySoftware developerException handling1 (number)Key (cryptography)Revision controlLine (geometry)Library (computing)Cartesian coordinate systemError message.NET FrameworkCodeFigurate numberWeightMultiplication signWeb browserArithmetic progressionFinite-state machineObject (grammar)Electronic mailing listSoftware frameworkSoftware bugData conversion2 (number)View (database)Message passingStack (abstract data type)System callSampling (statistics)Data managementSource codeSoftware testingUsabilityPointer (computer programming)Web pageRight angleAreaNumberGreatest elementDescriptive statisticsComputer fileData storage devicePhysical systemPower (physics)Computer animation
37:35
Software developerFigurate numberBlogStack (abstract data type)Video gameFeedbackLibrary (computing)Multiplication signFrustrationTwitterBuffer overflowRight angleUsabilityOnline helpTerm (mathematics)Thermal expansionGoogolTheory of relativityComputer animation
39:13
Software developerLine (geometry)TriangleTouchscreenCodeUsabilityArithmetic meanLibrary (computing)Logical constantRadio-frequency identificationSoftwareRight angleElectronic visual displayType theoryPhysical lawComputer animation
41:17
FrequencyTime domainUniqueness quantificationComputer configurationServer (computing)Visual systemWebsiteSoftware testingEncryptionSoftwareExtension (kinesiology)Sheaf (mathematics)Virtual machineWeb pageString (computer science)Computer-generated imagerySoftware developerCodeBenutzerhandbuchSoftware developerModule (mathematics)Web pageMultiplication signMereologyLibrary (computing)Right anglePlastikkarteWeb 2.0Scripting languageVideo gameDoubling the cubeConcurrency (computer science)Installation artDatabaseSet (mathematics)Valuation (algebra)PlanningServer (computing)Vector potentialLengthStandard deviationCodeVirtual machineProcess (computing)Computer fileVisualization (computer graphics)Formal languageGoodness of fitCore dumpData storage deviceDifferent (Kate Ryan album)CASE <Informatik>Perfect groupSlide ruleApplication service providerArithmetic progressionConfiguration spaceResultantSummierbarkeitComputer animation
47:17
Software developerVideoconferencingEmailMultiplication signBuffer overflowResultantData storage deviceForcing (mathematics)1 (number)Office suiteFilm editingComputer animation
48:54
Software developerComputer animation
Transcript: English(auto-generated)
00:00
I hope you all enjoyed the keynote because it was amazing. What a cool introduction to design. That was ridiculous. So I'm talking about how to make an open source project awesome. And a lot of people don't know how to get started on open source or how to contribute to a project or start a project. They've got an idea.
00:21
They really don't know how to share with people. So step one is write code. So step two, now I'm John Resig. John Resig is the creator of jQuery. So that's how it works. You just write the code, and then everyone comes and shows up and contributes, and now you're famous.
00:41
Is that how it goes? No, I don't think so. So like I said, the title of this talk is Making an Awesome Open Source Project. I'm Paul Betts. I work at GitHub. My Twitter handle is down there where you can't see it.
01:04
So before I talk about creating an open source project, why? So why should I do this? And I think the biggest reason is that you get to describe your ideas. You get to suggest to the world,
01:23
this is the way we should do things. And so imagine if you're, other professions don't get to do this. If you have really new, cool, innovative ideas on how to build a bridge, how do you tell people? Maybe write a paper. You can't get those ideas out, but you can just go ahead
01:42
and actually build something, which is really cool. So that's really cool. You get the experience of helping people. You solved a problem, and it was hard for you. And now you get to make somebody else's life a little bit better, which is really cool. Other reasons, you can get experience
02:02
in some other piece of type of code that you've never done before. So if you're a web developer, but you think desktop applications are cool because you're somehow from 1998, like I am, then you can just do it. And how cool is that? You don't have to try to get a job in an area
02:21
that you don't have experience in, and then they're like, well, you don't have experience, then you can't get it. And the cool thing is that if you want to get into an area of code that you've never done before, some sort of domain that you haven't done, like web development or whatever, you can just do it.
02:42
So participating in open source has a lot of benefits that aren't even all altruistic. You could just do open source because you want to build your resume. I can't build bridges to build my resume in bridge building. I have to have a job. So this is this kind of unique thing that us developers
03:01
get to do, which is really cool. It's kind of on a philosophical note. I think that open source is kind of like, I kind of think of myself as in the same domain as art or music or it's a creative thing. And so open source is kind of like art for art's sake. It's not commercial. It's not produced for a reason. It does have reasons, right?
03:21
But it's the purest form of our art form, so to say. So sharing code is sharing your ideas. You're describing the world that you want to see. You don't just get to wait for other people
03:41
and hope that they'll do what you want or hope that people develop the way that you think that it should be. You can actually do it. And if your idea is successful and you think that other people agree with you, then you'll see this grow and flourish, and that's really cool. You get to build the vision of the world that you want to live in in the future, like directly.
04:05
Nobody needs to tell you how something works. You don't need a manager. You don't need a VP of product planning to decide how people should develop software. You can just do it.
04:21
So this guy is Clay Shirky. And so he writes about marketing a lot. And he writes about how marketing is really transformative in an area of information. Marketing used to be all related to things. But as the world turns where everything is based on information and the internet,
04:41
then marketing is kind of the only thing, is what he says. And I kind of agree with him. It's about a few things. So marketing is such a loaded term. So people think TV ads and people trying to sell me stuff. But really, marketing, according to him, is much more open than that.
05:02
It's about a few things. It's finding an audience. Who are the people who are interested in this? And it's about, if everyone knew about what you're doing, you had an idea, and then just magically everyone knew about it, we wouldn't need marketing. And knew when to use it, and knew when not to use it.
05:22
So marketing is about that. It's about telling people how to feel about your code. When I see a library, I see jQuery. How do you feel about jQuery? Most people feel pretty good because it's a really solid library. How should people feel about your product or the thing you're building, your library or your application
05:42
that you build? And so marketing is really important. And it's a thing that I see a lot of people who start off in open source miss. And he uses this quote in one of his videos. You should watch. He gave a video, I think, to some business talk.
06:02
And he used this line, ideas that spread when? So a lot of people will get really disappointed with open source when they start out because they'll write this library and they'll put a lot of work into it. And then they'll put it online and then nobody will say anything. They won't get any comments, they won't get any contributions.
06:20
And so they're like, this open source thing sucks. I heard of it. I'd get all these contributions and people would love it. And so you need to be able to let people know about what you've written. And so marketing is kind of that. This is what my idea does.
06:41
This is when you should use it. This is when you shouldn't use it. This is what it's good at and this is what it's not good at. And so then people can make a decision. Like if they think that what you're doing is interesting, then they'll use it. And if not, then they won't. So that's kind of the core thing I'm going to talk about today is really like,
07:02
what's the difference between somebody who did really good code and then didn't say anything about it? And somebody did really good code, but also put in a lot of work into making it accessible to others. And so it's really a shame when people write a lot of cool code and then nobody ever finds out about it. That sucks.
07:22
So let's write cool code and then also make it accessible for other developers. So code should solve problems. It doesn't always have to solve problems. But if you want to make a library for a code,
07:40
I usually talk about libraries. I kind of like framework design syndrome where every program I write, I think, how can I make a framework out of this? So I always think about libraries when I'm writing code. So I always talk about libraries. So when you go about writing a library or whatever, some people think from a code-first perspective.
08:00
They're like, I'll make a class and then I'll make another class and then I'll wire them together. But the first thing you should step back and think about is, what problem are you solving? What problem do you want to solve with this? What difficulty do developers have now and how are they solving this problem? Because almost every problem is solved in a certain way.
08:21
Sometimes that way is really bad and you can improve it a lot. Sometimes that way is just a little better. If you write another dependency injection framework, then people will solve that problem many times. And maybe it's important, but people are already solving that problem in a number of ways that is actually pretty good.
08:41
So if you're thinking, what should my first open source project be? You should think about what problems are people having that right now just suck? They're just awful to solve. People do a lot of manual work. It's no fun. What problem can I solve?
09:04
So here's the bad news is the code is by far the easiest part of what you do. Everything about it from mailing list, documentation, maintaining a website, talking to users, that's the part that's work. The code is the fun part.
09:21
And the code is not the biggest part of what you do. A lot of work you do is just documentation and stuff like that. So we'll go into things that you can do to make, we'll talk about all that other stuff. I won't talk about code in this talk. So the first thing that you need to do,
09:41
generally the whole theme of this talk is imagine what you would want to see if you were using this library. Think like your user. So everything that Errol said about experience and user experience and design applies to libraries and code and APIs too. Your API is like the user interface to your customer,
10:04
to your user. And so you have to think about it like a developer. If you saw a library that had a random Google code page or whatever, and it had no description, it just had some code and a one-liner that said, this does something, would you use it?
10:21
Would you spend the time to read through all the source code to find out if it's cool or not? Reading through source code is an expensive proposition. It takes a lot of time. Understanding, taking that time to understand what's going on in a code base is really expensive. And people won't do it unless they're convinced that this is going to be worth their time.
10:45
So that's really the overarching theme. Think like a developer. Imagine how a developer that isn't you will approach this project. What will they see first? What's the first impression? So the first thing is, use NuGet.
11:02
That's a given, if you're using .net. If you're using Java, it's Maven, and Ruby, it's RubyGems, and yada, yada. Package managers have changed how people consume open source. It's huge. Before, using open source was this ridiculous thing of downloading a zip file and adding binaries and configuring
11:22
things, and you messed it up, and it didn't work. It was frustrating and awful. And NuGet has solved all of this in this beautiful, elegant way where you just click, and you're like, I want this. And it just does it. It's brilliant. So NuGet is the motivation, at least for .net developers, to really develop open source. Because now you have a marketplace, essentially
11:42
like an app store for your code. You have a way for people to find your stuff, and to use it, and to give you feedback. And so that's a huge deal. So if you saw this library, would you use it? Looking at that page, what does it do?
12:03
OK, if you can squint, you can see that it's an open source Java database. And I don't mean to call out this tiger.org in particular, but that page is so busy. What is going on there? There's so much stuff. And on first glance, you have no idea what's going on.
12:26
Even this, github.com, the site that's near and dear to my heart, is not a very good landing page. If people are discovering your library, especially new users, they'll see this and be like, there's 30 bajillion buttons
12:41
here. What do I do here? So this is not a good place for the first impression to your library. First impressions are very important. And so this is, for a user, not a very good first impression. For a developer, it's great, because the code's
13:00
right there. You just browse through, you can see all the stuff. If you're using the site yourself to commit to your own code, it's great. But if I just want to find out what the deal it is, the only thing that tells you what the deal about Signaller is is that one line and a link. And if that link is blank, then you've just got that one line that's supposed to, in that one line,
13:21
tell you everything you need to know about Signaller, or at least why it's interesting. The number one question you want to answer when you have a landing page or when people get started is, why is this interesting? Why should I spend my time on this library?
13:43
So in marketing, they call this a landing page. So landing pages, good landing pages have kind of these four things. What does it do? What do I use this for? What do I not use this for? How will this make my life more awesome
14:01
so that I can spend less time at work and more time fishing or, I don't know, doing the fun things that I like to do? Why is it cool? What is it different from its competitors, so to say? What's interesting about this in particular? What kind of audience is it? Is it for really functional, super-hascally nerds?
14:22
Is it for database stuff? Is it for line of business applications? Is this for me? That's the question that people ask when they view your site. So this helps you get an answer. Your elevator pitch. So an elevator pitch is if you have 30 seconds
14:43
to describe why something's cool, that's your way. It's really short. You don't have a paragraph. If you have three paragraphs, you've already lost. You have to be describing a really short, to-the-point sentence. This is the essence of why this is cool. And then at the end, we have a thing called call to action.
15:00
And so call to action is what should I do? I found out this was cool. And so usually, for libraries, a call to action is download the sample. So now I can get more engaged because now I can go and read some code and see some examples or maybe install via NuGet or install via Maven or whatever. That's my call to action.
15:20
Install it. Try it out. But having this way to really go forward and say, I found out this is cool. What do I do now? Oh, I do this. That's very important. So fortunately, GitHub has done a great job with this. So I'm going to do a demo.
15:51
So this is a library that I write called NSYNC because I'm terrible at naming.
16:03
Whoa, what's happening? So it has no website. This is my landing page right now. And it's very confusing. But I do have a README. And so on GitHub, one of the things we do is we really feature READMEs as a really important thing.
16:21
So README, you get to format it using Markdown, which is this text formatting language. It's like an easy version of HTML. It's a risk-friendly HTML, so to say, for static content. And so I wrote a README for this. And so the first thing you want to do, like first steps toward making this better, write a README.
16:41
When people see GitHub repos or other code repos without READMEs, then they're like, what do I this? I have no idea what this does. So here's the cool thing. So I can go to Admin. And I'm going to go down here to GitHub Pages.
17:02
And so what Pages does is it generates a static site that's stored in your repo as a branch. It's a branch that's completely unrelated to your code. But what it does is it gives you a little static site, like some HTML pages. You can put images in there, anything that's not dynamic. So you can also run Markdown through a library called
17:22
Jekyll, which lets you take Markdown content and it will format it into HTML for you. So that's kind of cool. You can do code samples in there. So I'm going to take my library and hit Automatic Page Generator. So I'm going to fix the casing because I am pedantic.
17:46
So I get a project name. So I usually just leave this the same. The tagline is copied from your description. I like that tagline. So NSYNC is like click once, but works. So the default body of the GitHub page
18:04
is like an intro page, like how to use it. So that's kind of cool. It's important to read, but we don't actually want to use it. What we're going to do is we're going to just take our README and copy paste it in there. So that's by far the easiest thing to do.
18:20
And I've already written README for this. So if I Google Analytics, which is free, I can set it up and put it in here as a tracking ID. That's kind of cool. So you can see who's using it and from where and what kind of browsers they use and all kinds of stuff. So I'm going to continue the layouts. So the cool thing is that we have
18:41
a ton of great designers at GitHub, and they made all these really nice templates. So a lot of people struggle because they'll put up some HTML and then it'll look crappy because we're all programmers and we don't know how to design very well for VC design. Maybe some of you do, I don't. I try and it just looks ridiculous.
19:01
So there's a ton of cool templates. And so it took my title, my tagline, and my README content and just threw it in here. So I kind of like this one. This is my favorite. Even though it's a default, it looks pretty good.
19:23
And so this is generating a default. You can actually edit this later. So if you don't like the templates that are already there, you can make your own. You can do whatever you want. It's just getting you started. And honestly, it gets you started in a really good way. So maybe you only want to make a few tweaks to this, but I usually just take what they give me.
19:41
So it looks great. So it looks good. I'm going to say publish. Cool. So now when I look, I have a new branch. I had a new branch. What's the deal? This is the worst demo ever.
20:02
Oh, here we go. So the cool thing is that you can run this more than once. So basically, you just keep running it over and over again. And each time, if you update your README, you can just run it again. So if I click this, now I've got a URL
20:22
that I can hand to people. It's super easy. And actually, you can take this and make a top-level domain. So I created a project called link to await. If I can type in this bar. .net, because it's .net.
20:42
And so what you do is you register a domain name using like dnsimple or GoDaddy. Don't use GoDaddy. As an example of a thing that you could register domains with, but you shouldn't because it's awful. But dnsimple is quite good. So you register that domain name, and you point it toward it.
21:00
And you actually just create one static file called cname in your root of your directory, and you just give it the URL. So in the GitHub pages for link to await.net, there's a file called cname. And the text of that file is link to await.net. So here we go.
21:21
So I have this really nice page where people can learn about what is link to await or what is in sync. And so I have code samples in here. It's really important. I think that Rubyists always did this really well. They always had a really nice front page, and it had the smallest code sample
21:41
that they could possibly make that just impressed you. It was just like, that's cool. And so this is the smallest link to await sample that I could come up with. That's cool. You can have some other information. At the end, of course, use NuGet install package.
22:05
So now, really, there's no excuse. If you create any project that you want other people to see, write up a readme, and then put up a GitHub pages of it. It's a great way for people who are finding your library to figure out what's going on.
22:21
Cool. So any questions, comments, concerns, rants, heckling? Wanted to ask before I move on and keep going. Cool. Like I mentioned, another thing that's really important
22:41
is documentation. So you have all these ideas in your head, and you wrote this library, and it makes total sense to you. But you've got to realize that you're in this bubble. It makes sense to you because you wrote it. So you have to take all that stuff in your head and then make other people understand it. And that's really difficult and almost way more
23:03
difficult than writing the code. I think that writing the sample application is far more difficult than writing the actual code. Because not only do you have to write the sample application and have it work, it also has to demonstrate what you want to demonstrate. And you have to think about, what do I want to demonstrate in the sample? You have to make it easy so that when people read this
23:20
code, they're like, oh, that's what it does. So the code has to be really clean and easy to understand. And it has to do all these things. So it's way harder, in my opinion. I once spent like 12 hours writing the sample for reactive UI. And it took me far less to write way more code.
23:42
But because I wanted it to be not only work, but be interesting and motivating and simple and concise, it took me a lot of time. It's a lot of work. So C Sharp, if you guys don't know this, I'm going to talk about C Sharp specifically,
24:01
uses XML documentation. And so at the top of every method, if you hit forward slash three times, it puts out this template. And so you write the documentation in the code. And then if you go into the build settings in Visual Studio in your C Sharp or VB project file, and there is an equivalent for VB. I think they just use a different comment syntax.
24:23
But with the build, it'll create like you have .dll, .pdb, and now you have .xml. And so .xml is the documentation. And so you can run this through this tool called Sandcastle to generate a chum file, like a CHM help file, if you're from like 1997 and chum files are cool.
24:44
But more importantly, if you take that XML file and include it in your NuGet package, now when people use your library, IntelliSense will give them the documentation. So like there, they knew up a class, and then you would dot and then highlight a method.
25:00
Not only do they see the method and its parameters, they see the help documentation as well, which is huge. Because people browse around with IntelliSense all the time and try to figure out what's going on. And so that's really a big deal. So always include, always write XML for at least your public methods, and then include it in the NuGet package.
25:26
So check out these guys. Check out Galloway's stash. It's amazing. It's so, I don't know, sinister.
25:42
So the three things, the thing that these three guys have in common is this Phil Hack, who's right there, and Jeff Atwood and John Galloway, is that they blog. They blog a lot. They do a lot of really awesome posts and developer education and stuff like that. So my next point is blogging is important, especially
26:03
in the age of Twitter. Because it's so tempting with Twitter to just like send off a response and help one person. But the problem with Twitter is that it's not searchable after a while. After like, I think the lifetime is like two weeks. All the things you said on Twitter that help people out and were interesting or motivating, go away.
26:24
Nobody will ever find them again. There's no global search for Twitter that lasts more than two weeks, which sucks. We're doing all this interesting stuff and then posting it and then generating some excitement, but then it disappears. There's no reference for it.
26:40
So this is why blogging is still important. So blogs are an awesome place to show examples. Blogs are an awesome place to show, how would I use this? Like common use cases for your library or your code. It's a place where you can write like longer form documentation. More importantly, it's in a place where you can like write the zen of your code.
27:01
Like why did you do this? Like what are the approaches you took and what worked well and what didn't? It's a place where you're not just writing like technical documentation. You can write some like prose. So it's really important. Like people look for that when they use a library. They don't just want to see like this method does this,
27:21
like a dictionary. They want to kind of understand how should I use this. And it's also a good place where you can do releases. Like where you do release notes like check out this new release of my cool library. It's got these new features, here's how to use them.
27:41
So it's a big deal. So another thing that's really important are a venue where users can talk about your project. And so the easiest one is mailing lists.
28:03
So other places are like a bug tracker. But bug trackers are really limited. People have a certain expectation when they go into a bug tracker. They can't discuss things on a bug tracker because a bug tracker is about issues and nothing else. I always struggle like issues are supposed
28:22
to be about more than bugs. But I always think of like what could it be? Like what is that tagline? Like thoughts? Like I don't know. We always want to make GitHub issues more than just bugs. But we have no way, we have no word to. English is such a limited language with its three bajillion words and I can't think of one.
28:42
It's frustrating. So mailing lists are cool because if you build up enough people on a mailing list, they'll start to help each other, which is awesome. I heard at Yuriko, a Ruby conference a few days ago, the author of Vagrant, which is this virtual machine
29:01
automation thing, so you can just like Vagrant up and it'll just build a VM for you. He said that he actually doesn't respond to anything on his mailing list. He rigged it so that every message that doesn't get responded to for over a week gets sent to a bug tracker, basically. His own bug tracker, like an internal one.
29:21
It's actually more like he uses like help desk software. And so really, he doesn't want to respond to a message unless it's a week old because he knows that other people can help out. And so mailing lists are searchable. You can find them over Google or Bing or Alta Vista, whatever. And so it's just like a place where people can find search
29:43
information, like they can go back to the log and see, did anyone else have this problem? So that's important. So one thing that you should never do is fixed user submitted bugs. I'll tell you why. So when somebody emails you a problem
30:03
and then you just fix it for them, you're wasting an opportunity. And the opportunity you're wasting is the opportunity to turn them into a committer. So you have the opportunity to kind of tell them, well, it's in this part of the code. Here's how I would think about fixing it.
30:20
And then just say that. Because then if it really annoys them, they're going to go fix it and submit a pull request. So what you're really doing is mentoring. You're helping developers to get better and understand and to work with your code. And you're helping them to, you're building committers. You're building collaborators. And that's really important. Mentoring is almost more work than just fixing the bug.
30:42
It might take you like three minutes to fix the bug, but you might work for like two hours helping this guy to fix the bug. But in the end, you end up with somebody who's going to help you to build this library. And in the end, you're helping them too. You're doing them a favor because they're becoming a better developer because they have somebody
31:00
who they can work with. It's a big deal. So you can build strong committers. If you're using GitHub, you do code review via pull requests. So a pull request is not just a way to send somebody else code. It's a way to talk about a feature.
31:22
So when you open a pull request, you have a place to talk about a title and a description. You describe like, why would I want to do this feature? What's the philosophy behind this feature? This is why we want to, I don't know, do this and that. And then as you write the code, you see it show up in the pull request.
31:40
So you make a commit, and then the maintainer can respond back and say, well, this is great, but I'd really like you to change these three lines. And you can comment on each line as well as comment on the thing as a whole. And so unlike other, it used to be in the subversion days, you had to delete that message and then send a new one.
32:00
That sucked. But pull requests, they keep going. So if he makes another commit, he makes three commits, and you comment. If he makes another commit, it'll show up in that pull request as well. And so it's this ongoing dialogue back and forth. It's like, well, OK, you fixed that. That's great. Now fix this. And so it's this awesome conversation
32:20
to store everything there is to know about this one feature. And so we actually, at GitHub, as soon as I start working on something, I make exactly one commit and then open a pull request. I've opened a pull request before I'm not even done. And so one trick to do with that is that I always,
32:41
in the description, put a to-do list. It's like, this pull request will be finished when I do these five things. And you can do it in like, if you use like a triple back tick, like the character that's left of one, like back tick, back tick, back tick. You can have just fixed width, plain text, like a code view.
33:05
And so you just put a to-do list in there, just like you do to-do.text. And then people can see the progress of the pull request. And then when it's all checked off, you hit the Merge button, and it's done. It's really cool.
33:21
So I said that documentation was important, but I have some bad news. Nobody will ever read your documentation. Every developer is guilty of this, so just have to use it. You've written pages and pages of beautiful prose that will be summarily ignored by everyone, but it's fine, because it's
33:40
important that it's there, because they'll find it eventually. But you've got to realize that when people first use your library, it's almost certainly that they're just going to start poking around. Developers learn by doing stuff. Right? And so don't look at this as like a failing developers.
34:00
Use it to your advantage. So things like XML IntelliSense is extremely important for that reason. When I go to use a library, I don't try to actually read any of the documentation. I just start creating objects, and I go through the object browser and say, this looks like what I want. OK, let's just use that. So naming, really important, because that's how people are going to discover
34:21
how to use your application. The best libraries are the ones where you don't have to read anything. You just look at the method list, and you're like, oh, yeah, I want that one. OK, we'll do that. OK, dot, OK, I want that one. That's right. That's what I want to do. And so that's really the key to that is you've got to think of scenarios.
34:40
What do people want to do, and how can I make that obvious? This is really important. It's really difficult, something you have to really put a lot of time into. If you really want to get good at this, take your library, take a developer who has never seen your library, and just sit them in front of it and say, do this.
35:01
The reason that if you read the framework design guidelines for .NET, they go through a lot of this, and they really like the reason that the .NET framework is so good, in my opinion, maybe not all of you agree, is because they did usability testing on their API. They sat developers in front of it and said, open a file and read some text from it.
35:23
How would you do that? And then they watched them. You'll see really quickly in a matter of seconds what parts of your API suck, because it'll just be unusable, and it'll just be like, how do I? And it's agonizing, because if you tell them how to do it, you're doing it wrong. You just have to sit there and watch them flail. And so when you watch them flail,
35:42
you immediately know this part we have to fix up. And maybe you'll see them just go right through and just figure it out. And then you'll be like, that part is great. So a big part of this, create great error messages. It's easy to just throw null reference exception.
36:02
But the fact is that if they don't see the code, the piece of code that they're in, they don't have your source code. So they'll just see a call stack that's like five deep. And at the bottom, they'll just see null reference exception in your library. And you'll be like, it's a bug in the library. This library sucks. So it's important to say, this is the thing.
36:22
If you can recognize common mistakes or things that a developer could do wrong and then tell them in the error message, it's like, you need to do this. You just save them a ton of time. And it feels like that they'll like your library more.
36:42
Quick start. So this is the thing that NuGet people started doing. And I think it's a really cool idea, because NuGet isn't just for packages. You can do other stuff with it too. You can take over it and do all kinds of clever trickery. And one of the things that people are starting to do is that they'll create two versions for their library. They'll create two packages. They'll create the library package.
37:00
They'll create what's called a quick start package. And so what you do is you create a blank project and then add the quick start package. And so it'll add the library, but it'll also add a bunch of sample code. It'll set it up so it's like it'll create the sample out of a blank project. And so that's really cool, because they're automatically
37:21
set up to start fiddling it, like changing stuff. And so they can really see how to use something. And it's really powerful. It's a cool idea. No other package manager is doing it. .NET is innovating right there.
37:41
So one thing I do for a library I write called ReactiveUI is that I set up a Google alert for ReactiveUI. And I set up a Google alert for all of the related terms, like it uses the reactive extensions, so I set up a Google alert for that. I set up a Twitter watch in my library so I can scan for people talking about it.
38:01
And so the idea to do this is not for hubris. It's just like, oh, people are talking about me. It's cool. The idea is to help people out. If you see people struggling on Twitter, like, ah, I can't figure out how to do this and that, this is an opportunity to make their life more awesome. If you see people writing a blog and they're like, oh, I had a lot of frustration with this,
38:20
it's either feedback that maybe you should change it, make it easier, or it's a chance for you to write in the comments, like, hey, how can I help you? This is how you do this. I sit on Stack Overflow all the time watching anyone who mentions ReactiveUI and try to solve their problems. And that's really cool because one thing you find out
38:42
is that somebody frustrated is a huge opportunity because that frustrated person, when you help them out, will instantly turn into somebody who's really excited about what you're doing. Not always, but sometimes. 60% of the time, it works every time. So that's really cool. You can take people who are angry and saying like,
39:01
this sucks. I hate this. This is the worst thing I've ever used. And then suddenly they turn to somebody who's like, this is amazing. I totally get it. That's a huge opportunity. Make everything easy. Don't make me think. So this is the title of a book,
39:21
Don't Make Me Think. It's a great book about usability. So like I mentioned, your API is the UI of your library. So you should make it really intuitive and straightforward. So the tagline of Rails is like, easy things are easy.
39:41
You have to think about scenarios. Like, what are people going to use this for? And make that easy. Microsoft makes this mistake constantly. Like, they make it so that everything is possible. It will always be really flexible, and you can always do anything. But to do anything at all, you have to do a ton of work. I remember setting up DirectX.
40:01
I just wanted to draw a triangle on the screen. And that was like 300 lines of code of enumerating displays, and figuring out devices, and going through device capabilities. That sucks. Hard things should be possible, meaning that not everything should be easy. If you make everything easy, then you're
40:20
compromising in your design in some way. You can't make everything easy, it's just not possible. But you can make difficult things possible. So another line I really like that they use at Microsoft sometimes is fall into the pit of success. The right way should be really obvious and hard to miss.
40:41
And the dumb way should be really, you know, you should have to work to do something wrong. Donald Knuth, you know, he said like, one of the flaws of LaTeX is typesetting software, is that it's really difficult to make ugly documents. Which actually isn't true, but I'd like it to be true. I wish it were true, right?
41:04
But that's a cool idea. Like, I'm sorry, if you want to make something ugly, then this tool is not for you. Because it's going to be a pain in the ass. You're going to fight it on every turn to make something dumb looking.
41:26
If you write huge pages of documentation, nobody's going to read it, right? You got to break that up. You can't write all that text, nobody's ever going to figure out what's going on with anything, right?
41:41
It's pointless. Don't even bother writing it. In fact, if you're writing it, you should think of that as not a good thing, right? Like, the things you have to describe in your user manual are the things usually that you messed up. Because if it was obvious, then you
42:00
wouldn't even need to say it in the user manual, right? If you have to explain something and go to it at length to say like, oh, you've got to do this, and then this, and then this, you should just get rid of it. You should fix it so that you don't have to do this. And sometimes that's not easy. Sometimes that's a lot of work. But on the flip side, you have the potential to waste thousands of hours of developers' time.
42:22
This is not good. On a more positive note, you have the potential to save developers thousands of hours of time, right? So I wrote this library called Sass and Coffee. So what it does, it's an ASP.NET HTTP module. And it lets you use Sass, which is a CSS templating
42:43
language, and CoffeeScript, which is a JavaScript that's way cooler, right? And so there are other libraries that did this, right? Different pieces. But none of them were easy to use. They're all just like, you have to set up web config, and it didn't work right. And you had to fiddle and do all this stuff. None of them were on NuGet.
43:02
And so the goal of Sass and Coffee was not to be the fastest or like the most featureful. It was to be as easy as possible. So literally, the way you use Sass and Coffee is that you add the NuGet package, and then you create a file that ends in .coffee in your script folder. That's all you do. There's nothing else.
43:23
And so to do that, I had to do all kinds of crazy things. Like I took the install.ps1 and was adding stuff to the Visual Studio folders so the Visual Studio wouldn't think that a CoffeeScript file shouldn't be deployed. I would do all kinds of like wiring up web config for any possible scenario that could happen,
43:41
whether you're using Cassini or the IIS Express. I actually embedded V8 inside the DLL and embedded IronRuby so that you didn't have to install Ruby on your machine. It would actually, it included like pieces of the Ruby standard library as resources. And then I would redirect every time
44:00
Sass would try to read part of the Ruby standard library, I just redirect it to a resource. All these things were a pain in the ass to write, but it made it at the end of the day so that developers didn't have to think. They just added the library, and it all worked. It was magic, which is really cool. Not cool for me. I spent like hours in Wind Debug, but for developers,
44:23
it was really cool. So sum it all up like that guy from Scrubs. Scrubs is an American TV show that may be here, may not be on it right now if things make it over the pond. Anyway, it's not just about the code.
44:41
It's about all those other things, marketing. It's about documentation. How people use it. Make it easy for your users. Make it so that they don't have to fiddle. You write complex things so that they don't have to write complex things. That's kind of like the core of why the web is so successful.
45:01
The two main things that web uses are an HTTP server and a database. Both are extremely complicated pieces of code. And normally it's complicated. But the cool thing is that every developer doesn't have to think about those things anymore. They're just like, I'm just going to throw a request at a database, and then it's going to give it back, and it's going to handle all the locking and concurrency
45:20
and data storage and performance stuff, and it's just going to hand me back the result. It made it so that instead of every developer having to fiddle with all these concerns, one really smart developer fiddled with that concern and hated his life for a long time. But then at the end, the rest of us didn't have to. And that's like the core of a good library.
45:40
It's really cool. So developers don't read anything, which is OK. But we're going to optimize so that when they don't read anything, we're going to make their lives easy anyway. Yeah, make everything as easy as possible. I said that twice because it's really important and because I wasn't paying attention to my slides.
46:01
Very important. So thanks. So questions, comments, concerns, thoughts?
46:40
It's not done yet, though.
46:41
I made a lot of good progress on the plane, but it's getting there.
47:06
I was supposed to be here at the start of the talk in case you need something. Well, I didn't need anything, so we're all worked up. It's all good. It's perfect. Yes, do evaluations, I guess.
47:21
Oh, you're already gone. Never mind. I told him to do. Is it only at this door? I think. No, I don't want it there. OK. Phil is the only evaluator, and he gave me green. 100%. No one else may evaluate.
47:41
Oh, everyone. Oh, I thought they all had to go this way, so we were going to force them. Hi. Hey, Russell. Paul. Let me try. Excellent time. The best ever, one star. Yeah. Oh, sweet. OK. So I was in overflow. I watched most of your videos.
48:02
Yeah. I mean, send me an email. OK. Yeah. This is great. Thank you. You were awesome.