By Gregory Koberger, Founder at ReadMe.io.
Background
Before we get too far into the stack, a bit about ReadMe! We’re a fresh take on documentation. Yeah, that boring thing you spend most of your job reading or writing. We want to jazz it up. Documentation is the UI for any API or library, yet it’s treated as an afterthought.
We build developer communities that reside on a subdomain. It’s documentation, but with a heavy focus on community: suggested edits of documentation, support section, comments, and more. For example, your ReadMe page might be developers.yoursite.com (and would be branded to match your actual site). So, we have an admin panel where providers can produce the content, and individual “developer hubs” (basically, documentation, support and API dashboard) that are consumer-facing.
Some of our favorite customers are Apache, Box, Yammer and Mozilla. We have a nice mix of public company APIs, open source projects and internal knowledge bases using ReadMe.
ReadMe currently provides the developer experience for over 15,000 projects, and has been read by over 800k developers. Here’s how we built it.
JavaScript Everywhere
ReadMe is JavaScript, head to toe. I’ve been programming for over a decade, and over that time many languages have had the dubious distinction of being my “main” language. I cut my teeth on PHP, experimented with Java in college, was a proud Pythonista for a few years at Mozilla, and switched to Ruby while freelancing.
When it came time to do ReadMe, though, I decided on a language I simultaneously had never touched and knew intimately: Node. I had been using frontend JavaScript for a decade, but never took it seriously. Like in a John Hughes movie when the guy realizes his perfect girl was there all along, JavaScript took off its glasses, let down its hair, and won me over.
For the first time, I felt at home with a language. I had friends who loved Ruby or Python, and while I liked and appreciated them, they never clicked for me. With Node, it just felt right. Over a decade of programming all came together, and for the first time I truly enjoyed writing code.
Node is lightweight, yet powerful. I feel like the hard parts of programming are abstracted away, without ever feeling like I’ve lost control to “magic”. Frontend JS gets a bad rap for a bunch of reasons (browser compatibility, the DOM API, lack of new ES6 features, etc), most of which go away when using Node. (Sure, there’s still some rough edges left — but hey, that’s true about any language.)
I like the approach to packages, which vaguely follows the Unix philosophy:
This is the Unix philosophy:
Write programs that do one thing and do it well.
Write programs to work together.
Write programs to handle text streams, because that is a universal interface.
Like I said, for the first time ever, I feel completely comfortable with a stack. This scares me a little, actually. I’ve always prided myself on staying up to date with new languages and technologies. If I like this stack too much, I’m worried I’ll lose my incentive to keep exploring.
The Rest of the Stack
I spent enough time waxing poetic about Node, so I’ll speed through the rest.
Our frontend framework is AngularJS. The whole Angular 2 debacle means I can’t really recommend it anymore, but I love it. It comes with a hefty learning curve, but once you stop fighting and give in to the Angular Way, it all comes together nicely. Data binding has changed the way I write JavaScript, and turned piles of spaghetti code jQuery into two or three concise lines of $scope-laden AngularJS code. On our dashboard, I can turn out new features in 10–20 minutes using Angular.
Our backend framework is Express. Our HTML is Jade and our CSS is Stylus. I probably would have rolled my eyes a few years ago, however the lack of brackets and curly braces has grown on me. I find it cleaner to read and write. For Stylus, the mixin syntax beats Sass hands down: there’s no remembering what needs a browser-prefixing mixin, nib takes care of everything.
Our database is Mongo. Remember when I said I love the current MEAN (Mongo/Express/Angular/Node) stack we’re using? I do. But Mongo is the one weak link to me. It’s not horrible, and I actually like a lot about it… but often, it feels shoehorned into JavaScript / JSON. Mongoose does a lot to alleviate these issues; most of the problems I have are successfully abstracted away by it. However, ReadMe has a pretty considerable hierarchy, and keeping all the denormalized references (yes, denormalization is the recommended approach) both synced and fast isn’t easy.
I don’t see us switching from Mongo anytime soon, though. I like Postgres, however I really like the freedom provided by Mongo. We’ve started using Redis for caching; this has sped the site up a lot.
Our search is currently really bad – just a Mongo full text search. I spent some time fixing it up with Elasticsearch, but it’s been sitting in a branch for a few months. It was better, but still not ideal. People have a high bar for search these days, and Elasticsearch was good but not perfect. Elasticsearch is powerful, and I’m sure we could get it there with tweaking. However I’ve recently been playing with Algolia, and I've been loving it so far. We’ll almost definitely be using Algolia for our search.
Services
On to the good part: the third-party services we use! I like to think of myself as an intentionally lazy developer. I’m the only developer/designer working on ReadMe, so development speed is important. Rather than spending days rewriting things myself, I offload the work to existing services/packages/etc whenever possible. After all, that’s my whole theory with ReadMe: let one service do one thing right, rather than everyone individually reinventing the wheel.
Payment is done with Stripe, of course. Stripe has been a huge inspiration for ReadMe, and we owe it a great deal of gratitude: it wasn’t until Stripe launched that people started taking documentation seriously.
We wouldn’t be able to make sense of our Stripe data, though, without Baremetrics. I’m sure everyone involved has their reasons, but I can’t believe Stripe hasn’t bought them yet. Before, I had no clue what was going on. With Baremetrics, I understand our customers: how much we’re making, what our growth is, who is churning, who has a failed credit card charge, and more.
Speaking of making sense of users: Intercom. I can’t fathom starting a SaaS project without it. Before, we had some dashboards cobbled together listing our newest signups. I barely knew anything about our users. With Intercom, everything is in one place: we can see details about our customers, communicate with them, and more. If Intercom ever shuts down, so will ReadMe. That’s how vital it is to us.
Last (but not least) on the “understanding users” front is Clearbit. Clearbit is amazing for figuring out who your users actually are. We’ve had a ton of users sign up with their personal addresses, and we never would have realized they were VP of Something Important at Awesome Company if it wasn’t for Clearbit.
We’re hosted on Heroku. We were using AWS up until, like, a day before launch. At the last minute, I switched over. I didn’t have the time nor skills to manage AWS servers. Learning all the ins-and-outs of AWS can quickly become a full time job. With Heroku, it (usually!) just works. So far, I haven’t regretted it at all — although I can see us making a switch in the future. I’d love ReadMe to be backed by git, and that’ll require some crazy stuff on the server.
Our database is on Compose.io (formerly MongoHQ) for the same reasons. ReadMe uses Mongo, Redis and Elasticsearch, and after a few weeks of trying to get them to all work and work together and scale, I gave up. Thirty seconds into using Compose, and things were working like a charm. With one click, you can set up any of the databases. They have connectors between Mongo and Elasticsearch, which keeps the data synced. It has saved me weeks of work, and I’m much more comfortable having them host the data than trying to manage it myself. They know what they’re doing, whereas it was far outside of my skill set.
Some other quickies. We use FilePicker for file uploads, which are stored in S3. We use CloudFlare to cache our main website. Our emails are sent using Mailgun. All our code is lovingly hosted on GitHub. All communication is done via Slack. We use Heap for our dashboard analytics. Since it’s Angular, Heap’s way of tracking all clicks has been so much more useful than Google Analytics. We use Logentries, New Relic and Airbrake for monitoring. We don’t need all three, I just don’t really love any of them and haven’t figured which to settle on.
Great Time To Be Building
I couldn’t have built ReadMe 10 or even 5 years ago. I’m the only developer/designer, and I initially built it on a razor-thin budget. The only way I was able to do this was by leveraging dozens of awesome open source projects and services.
The speed in which I was able to build ReadMe is a huge testament to how good tools are getting, and the future has me excited… and maybe a bit worried about job security. But overall, this is an amazing time to be a maker.
(Like the sound of this stack? ReadMe is hiring. Come help us make documentation fun!)
4
1378
