Presentación
Vídeo
Transcripción
Extracto de la transcripción automática del vídeo realizada por YouTube.
- [Mat] Alright, what's up everyone. How's it going? So who among you has ever released a Gem? Okay, good, I like it. Okay who has released a popular ass Gem? Like, tons of contributors, tons of users, tons of love? Okay, alright so we wanna get from like group one, and not group one, everyone into group two.
Okay, so that's what's we're gonna do today. Before I get started, quick intro, my name is Mat, what's going on? If you wanna tweet insults, that's a zero. I live in Brooklyn, looks like this, I work for Genius, we're a platform for annotations. One time John Resig used our platform it was really cool, and here's my talk.
So, I'm gonna talk about seven specific things. That are going to make your Gem more appealing, it's to make your users happy. Right, so your Gem should make users happy, of course, this is a Ruby conference so, we're gonna talk about first how to get your users up and running quickly.
We'll talk about how to write really good documentation. We'll talk about how to change your Gem without causing your applications pain. We'll talk about how to coexist with your users applications environment, in a nice way. We'll talk about how abstractions can lock people in and how we can prevent that.
And we'll talk about how to make it easy on your contributors by giving them an easy to run test suite, by giving them automatic feedback on their contributions. So, I'm gonna start by talking about quick start. So Sinatra, great Gem, really great micro probably the best microframework I think, Sinatra, really great Gem.
And take a look at this, the top this is the top of the Sinatra readme. This is the quick start, it's four lines long. Which is amazing, there's four lines of Ruby. And then you know, like the Gem install, which doesn't even count, and one line to type into your shell, and you're good to go.
And this is what we should all aspire to, right? We need a quick start that's this easy. And that's what as Ruby programmers we expect. And we don't expect that because we're not smart, or because we're lazy, we expect it because we wanna spend our time building beautiful, functional, wonderful products, not installing things and configuring them.
Having a really short good quick start is actually a feature of your code not of your readme, right? You can't write a short quick start unless your Gem allows it so how do we get to that point? Well let's think about how we we usually write a Gem, right? So, probably what happens is I am working on my application, I have some code that I think, ah I should open source this, this would be useful to some other people.
So I take the little bit of code out and I you know create a new directory for my Gem and I probably stick something like this into my Gem file so that my application points at the local version of the Gem while I'm developing it. And then I go on, you know I might write some tests in my Gem, might flesh out the interface a little bit start writing documentation, and at some point I'll probably go back to my application and say okay well does this all still work with this Gem that it's now pointing at that I've been developing? But what I've never done at this point is actually feel what it's like to start using the Gem from scratch.
To start it in an application that doesn't use it already. So something that's worked really well for me is to just basically make a, like an example app. Doesn't have to be a rails app, whatever makes the most sense for the problem that you're solving. But make some sort of example app and really think okay, if I wanted to do this, if I wanted to use this, for some plausible use case, what does it feel like, what does it look like? I have always found at least one pinpoint that I can solve to make it easier to get started using this technique so, getting that quick start down is all about just putting yourself in the position of a new user, which is something that doesn't necessarily come natural.
now, once you got the user hooked, once things are installed they want to learn more. They want to be able to easily find out everything that your gem has to offer. So that's where documentation comes in. And we're back to Sinatra. Sinatra not only has a great quick start but check this out.
If we start scrolling down, like we're still in the Table of Contents right now. Okay, still in the table of contents and then finally this'll take about a minute to get through the whole thing. Sinatra has an incredibly long readme. And that is a very very good thing.
So there is nowhere that is more discoverable for documentation than the readme, right? It's there front and center in Github, it's there front and center when you have generated code documentation, it's there on airplanes, it's there if you don't have the internet because it comes with the gem when you install it.
So the readme is a really important place to give, to lay out a full map of what your Gem is capable of doing. And in order to do that, I recommend making the readme a part of your development process just like say testing is a part of your development process.
So you wouldn't, you wouldn't submit a poll request or you wouldn't necessarily make a commit with new code that doesn't have some new tests. And you can take that a step further and say I'm also going to submit any time I add something new to my application I'm also gonna add something new to the readme.
And you can take that a step further and write the readme first. So actually think about before you lay down any tests or code think about how how am I going to explain this to my users. And you might end up writing a better interface once you think about in that term than those terms, then if you document after writing.
So the readme is really good it's really important. Again, sort of every feature that your Gem has, every major thing you can do with it, I think should appear in the readme. Very searchable, Command+F great tool. But of course the readme can't be totally exhaustive.
The readme can't take you through tons of examples of every method, it can't take you through all the possible options you can pass and that's what inline code documentation is for. So what we've got here is from Addressable. Another great Gem, and Addressable is using this param and return tag you can see here.
And that is not built into standard RDoc. That is actually a documentation tool called YARD. So that stands for Yay A Ruby Documenter. And YARD adds a bunch of extra structure to Ruby code documentation that isn't in the built-in documentation for Ruby. And what's nice about this is that you know, Ruby doesn't have a lot of structure.
As a language you know, it's not statically typed. Everything's mutable at runtime, there's all this meta programming. And that's great you know that's really good for us as programmers, but it does make it difficult to communicate the nuance of power code works to users who are experiencing it for the first time.
So basically this is sort of the YARD tags act as a counterpoint, which have a lot of structure. That could really explicitly communicate hey this is the type we're expecting here. You know, there's no type enforcement, but this is what we expect you to pass us this is what we're gonna pass back to you.
And then it generates really nice looking documentation like this. So YARD has dozens of tags, these are some of my favorites. Of particular importance I would say, the @api tag, so Ruby visibility we can do some stuff with it but we can't say, make a class private.
[ ... ]
Nota: se han omitido las otras 3.733 palabras de la transcripción completa para cumplir con las normas de «uso razonable» de YouTube.