this is an awesome site. This is the coolest documentation site I've ever seen. Anyways,

my name is Sam and we're going to be talking about documentation. I make videos for Ember developers on embermap.com if you don't know who I am. I love documentation sites.

They're great. Look how beautiful they are. They're such an important part of our workflow as developers. We use these things all the time, how they look, how they work is just critical to how productive we can be. When I made Mirage and put together a doc site a few years ago, I looked at what was available at the time and I wanted to

make something that looked pretty good, had versions, was clear, made it easy for contributors to edit and update, and this is kind of what I ended up with. And some of you kind of squint your eyes and you look at the left-hand nav and the top nav, you can see that they're very similar and that's actually because Ember slide deploy's doc

site started as a fork of Mirage's. And if you look at power select, you'll see the same thing. So that was pretty cool. You know, folks liked what I came up with and that worked for a bit. Now I was really interested when I saw LiquidFire's doc site

because Mirage's doc site was made with Jekyll, which is a static site generator from Ruby. But Ed, for LiquidFire, needed more than just a plain static site. He wanted a whole Ember app because for his documentation site to be effective, he needed to demonstrate the components, the Ember components, that came with LiquidFire. And you can see the same thing for Ember concurrency here with

Alex. And so really, a static site wasn't suitable for these, you wanted a full fledged Ember app. So as I kind of, you know, I like documentation and was looking at all these different sites and taking kind of a survey of the

community, I asked what any good Ember developer who's been sufficiently brainwashed would ask, which is, what can we share, right? Because we have all this great infrastructure and when we see people doing the same thing over and over again, there's an opportunity there for us to build up to a higher floor. And it turns out there's actually quite a lot we can share. So this has

kind of led to this project, Ember CLI add-on docs, which I started and which Dan Freeman and Chris Garrett joined along with, and I just want to give you a quick tour of some of the features. So first thing is the shared styles. If you're an add-on developer, you don't want to have to think about this from scratch every time. So if you use add-on docs, you get a nice looking

site from the beginning. So these two screenshots are from Ember CLI add-on docs documentation site, and add-on docs is an add-on that's documented with add-on docs. Yeah, so that's its inception, it's super meta, so but it's really cool. It's like the dog fooding of a startup kind of thing, you know. So

anyways, this is what it looks like, so that's pretty cool. We get auto-generated code snippets, which is something else we borrowed from Ed and LiquidFire's docs, because you don't want your documentation code to fall out of sync with the code that's actually running your doc site. We have components that make it easy to have live demos in your app. So this is

Storefront, which is another another add-on I work with that's documented using add-on docs, and here you can see there's a demo here that's showing you how to load data using Storefront, and this is the actual code that's running in an Ember app, and it's using Storefront's APIs, and it shows you the code that's powering that demo, and that's all right there for you. So

having that in the add-on gives you a really great testing story, because the Ember app that you use for your documentation is actually the dummy app that comes with every add-on. So if you've never written an add-on before, add-ons come with a dummy app, which is a full-fledged Ember app, but it ends up being a perfectly suitable place to put your documentation site,

because it's already wired up with all the dependencies and all the components and stuff that you're defining, and so if you write your documentation site using the dummy app from your add-on, you can write acceptance tests against it. So looking at this demo, I can test, I can explain how a Storefront API works. I can write a test against this and make

sure that actually when you click the thing, the right data is loaded, and the right stuff shows up on the screen, and that way not only am I making sure my APIs work, but my documentation site is also tested, so my docs will never fall out of sync with my actual add-on. So that's pretty awesome. That was another trick from Ed, by the way. He basically comes up with all the

ideas. We also auto-generate API reference from your source code, so this is add-on docs current site, and you see add-on docs ships with a lot of components. All these pages, the entire nav section under API reference is auto-generated from either YUI doc or ES doc comments in your source code,

and these go beyond just the plain comments. These are actually, we do some extra logic to make it more suitable for Ember add-ons, because this whole project is laser focused on the add-on use case, so you see here when I click demo, you can actually see the contextual components that demo yields, and we're gonna add some more filters and all this stuff to clean

this up even more, but that's kind of the idea. Now you get version docs for free, so the pattern with GitHub is to use the, we deploy to GitHub pages, and typically when you do that, you blow away the old GitHub pages repo, and so you just smash master each time and you just get one version, but

we have some code that manages it so that every time you tag a release and publish it, it builds that dummy app and it puts it in a subdirectory, and so every time you tag your project and build it and deploy it, you'll get a new version of your documentation site, so basically every add-on we'll get should, using this, we'll get version guides for free out of the box. That's pretty cool.

And then finally, one really cool thing we can do is implement search for you, and that's because all of your docs are in the code base, they're all in master, so the dummy app lives in master alongside your code, and all the comments on your classes are there as well, so we can scrape that, parse it,

and build an index and ship that with your Ember app so that we can just give you search for free, and this will search over all your guides pages and your API reference docs. So the goal for this add-on is to be a no-brainer for every add-on author to use. There's a lot of different features, and you

know, sometimes you might want to use all of them, sometimes you might want to just install it and use a few pieces. Right now, there's, you know, it's still work in progress, but eventually the goal is that you can just install it and use whatever piece you want, so if you're excited about this, then I'd encourage you to check out Ember CLI add-on docs, and thank you so much for your time.