This is the final post in our series on the tools we use at ReadMe.
We’re a fresh take on documentation. Documentation is the UI for any API or library, yet it’s treated as an afterthought. It’s the boring thing you spend most of your job reading or writing. We want to jazz it up.
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.