Laying in bed at night a few months ago, an idea came to me: Urban Dictionary for code.
Countless times, I’ve google how to do something, only to be bombarded by opinions and definitions for related tools. I’d google Rails and be told that I should use SQLite instead of Postgres, and that MVC is on decline and I should hook up to an MV * front end framework, and that I should install some NPM packages (but… Rails uses gems?) and so on. By the end of it, I’d be left confused and overwhelmed. My well-meaning dev friends weren’t much help – they’d dive into the complex of the topics, debating the performance merits of tools whose purpose was beyond me. I felt dumb. I just wanted to know a few things:
- high level, what does this do?
- how does this tool connect with everything else I’m building
- is this worth learning right now?
A few days passed, and the idea nudged me again. I decided to share it with two subreddits – r/webdev, and r/learnprogramming. Reddit is fickle, and something interesting happened. r/learnprogramming gave me a score of 0 and a few cautionary comments, warning me this wouldn’t be useful.
r/webdev on the other hand… said “hell yes”. I got a lot of really encouraging responses, and a spirited debate on the merits of such a tool.
I knew I didn’t have a moment to lose. With such an overwhelming response, I had to build this thing. I was excited and more than a bit nervous – after all, r/webdev is a community of developers (though also more than a few learners!) Users also brought up some great concerns about the accuracy of oversimplified definitions, trolling, and similar resources.
Nevertheless, hundreds of real people had a passionate, largely positive response to my idea, and I was pumped. I set up a Trello board and started wireframing.
Not pictured: fear and ambiguity
After QRL, I was fairly confident I could get at least an MVP of the app up – but this app was going to be entirely driven by the community, with visitors contributing to definitions (and ideally moderating.) The top comment was – open source this. I had no idea how.
* * *
First attempt at instant search
I built the initial website with the core features – the ability to search and add new terms and definitions – pretty quickly. I also implemented my best attempt at “instant search”, sending a regex-powered request for similar terms after every single letter the user types. This was a fun mix of front-end design and coming up with a sorting algorithm.
Voting was a little trickier, but I managed to create a clone of a Reddit/Stack Overflow type upvote/downvote system.
Next, I turned to the user profiles and well as moderation tools. I wanted to create a minimal barrier to creating new definitions to deter lazy trolls and very casual users from cluttering up the websites. So, I decided that similar to reddit and Stack Overflow, anyone could vote on definitions, but users would need to log on to add new definitions. I wanted to keep accounts as slim as possible, so I created a reddit-style, minimal signup workflow – just a username and a password. No email confirmation, or password confirmation – at least not until the website got some users.
First attempt at signing up. Missing: password reset
I also implemented bcrypt, and finally started to thoroughly understand how hashing, and salting works. In the past, I’ve used the Rails gem (thank you, Michael Hartl!) but it never fully clicked. Now, hello, secure passwords!
Working on the front end made me really want to use components and nudged me to finally learn React (which I’m going to do next.) In the meanwhile, I learned to use Handlebars.js side by side with jQuery. This allowed me to move my definitions into a separate HTML file instead of jQuery-appending an incomprehensible string of HTML.
This also massively helped with the Admin board I set up next. I wanted to initially moderate submissions (again, to have a little control over the quality of the content), so I set up a system where I – or a moderator – would need to approve the first 5 submissions for every user, after which a user will have earned the websites trust, and could add endless definitions immediately. I figured, again, that this would deter the lazy trolls from making endless accounts to spam.
I spent a lot of time thinking about the relationship between quality control and the user-generated nature of the site. At this point, I had no idea how I’d moderate, or what standards I’d even set in place. I was okay with the idea of not-100%-correct definitions (and definitely wouldn’t be able to judge the quality of all the different CS topics), but I wanted to make sure that every definition on the site at least made an effort. I didn’t want the content to become heavily subjective, opinionated, or devolve into in-jokes. Moreover, I wanted to prevent posts unrelated to programming. I had described the site as an “Urban Dictionary for code”, drawn drawn to the “in-the-loop” nature of Urban Dictionary posters – not its vulgar, in-joke culture.
At this point, I wasn’t worried about the side getting flooded with trolls bent on posting offensive content – I didn’t think I’d ever be that popular. Rather, I was concerned about low-effort, inside-joke, trashy content (ex: “Rails is the sexiest disaster from 2004″)
* * *
A week in, my project was coming along nicely, and I had finished the core features and admin board. The last MVP feature left to build was comments – and I had some ideas for a cool, post-MVP way to improve these into a helpful, unique feature.
I was really grateful for my Trello board – it kept me on track, and I always knew what to do next. Whenever I got new ideas (which happened very often) or noticed bugs that weren’t worth fixing immediately, I’d just add them to the board and prioritize them, freeing up my mind to focus on the highest priority stuff. I noticed my mind wandering and darting between parts of the app a lot, so it was really helpful to turn to my board. It was also gratifying to see how much I had already done (despite how much work was left).
My Trello board, a week in.
Next up, I had two tasks that intimidated me:
- defining my post philosophy and guidelines (“what should ideal content look like”?)
- coming up with the website design.
* * *
Around this time, I began to get lost in my own project. In a rush to get things up and running, I coded quickly. That’s not to say I had no structure – in fact, I created my Trello board and schema precisely to know what I’d need to code next. However, I was now far enough into my project that my highest priorities weren’t always blatantly obvious, and I was faced with a lot of “important-but-not-crucial” tasks. I had prioritized my work into “must have/important/nice to have/not crucial” tasks, and I’ve built all the “must have” tasks. That is, I finished all the things that were absolutely crucial for the website to get off the ground. Users could search for definitions, vote, and add new definitions. I had set up a database, and deployed the site. Now, I needed to get through all my “important” tasks – things that were pretty crucial to a good experience, but not essential for the website to run – comments, notifications, mobile design, password reset, moderation, etc.
I found myself struggling to pick what to work on, and often reverting to small design fixes to feel like I was doing something, all while avoiding tackling the next big feature. Beyond a lack of prioritization, certain tasks (like adding notifications when a new term submission was approved or rejected, for example) mean that I needed to dive into the less-than-ideal structure I had set up.
The lesson seemed to be: prioritize harder, and plan ahead further. I kept seeing how important my Trello board/schema/wireframes were during the design process. As a friend described the process, I had consciously taken off my product and project manager hat, and put on my developer hat – and as a developer, I didn’t want to think about prioritization. I just wanted to code and solve technical problems.
That’s not to say I didn’t see this coming – I knew planning was important, which is why I tried to plan ahead to begin with. What I was discovering is that it planning was crucial, and I’d surely plan even more in my next project.
* * *
I had to constantly remind myself I was building an MVP, that I needed to get this to users as quickly as I could, and then learn from their feedback, not my impulses. Around this time, James helped focus me by reminding me that my job was to get out barebone versions of the crucial features, not polished versions of some features. I would often find myself digging deep into something obscure, like updating text fields on login without refreshing the page – inconveniences the early adopters would surely forgive me for – while ignoring tricky-but-crucial features, like password reset.
I also tried to keep impostor syndrome at bay. I was building an app with Express and jQuery, with no front-end framework, no Mongoose, no ES6, with callback hell in my code – in short, with a million opportunities to stop and write better, fancier code with newer technologies.
Finally, I got the app to a place I was happy with it. The big test was simple: would users like this? If they did, I could spend more time with it and improve it based on their feedback. If they didn’t, I’d move on to something else – like learning a fancy front-end framework, Mongoose, and ES6.
The next step was exciting, but also new territory – getting beta users and seeding the site with definitions.
* * *
At this point, I showed the website to my girlfiriend Jenn and my friend James. They were the first to see the site, and it was immensely gratifying to watch someone go through it as a user would. Both found a number of bugs and inconsistencies, and were confused by a few of the same features, which was very helpful. James also noted that the website UI felt old and looked like a classic dictionary, counter to the product I was trying to build – a dictionary of cutting edge tech terms.
I now had two Trello cards full of bugs to patch and revisions to make, as well as a design makeover to tackle. The design bit concerned me, because design is not my forte, and I wasn’t sure how to revise it. I’d love to say that I jumped back in and fixed everything, but in truth, I was frustrated and sad. I wanted my product to be perfect right off the factory floor, and it was far from it – even to the people closest to me (whose job was, of course, to be brutally honest). Discouraged, I took two days off and tried not to think about code.
* * *
Although it stung at first, my session with James was very helpful. He pointed to a few design elements that felt outdated – but more importantly, I started really paying attention to the websites I visited. Normally, I’d pull something up in the inspector if it caught my attention. Now, any time a website struck me as sleek or modern, I would pause and try to zero in on the elements and aesthetic that created this feeling. I’d then open up the Dev Tools and dig into why. I knew that I had made timid color choices – not knowing what to pick, I stuck to a few shades of green, beige, and brown. So, I tried to make the colors bolder. I paid attention to the way others use box-shadow and gradients, thin fonts, icons (at James’s suggestion).
UI, Take 2
At the same time, I wanted the site to be as fluid, unobtrusive, and undemanding of the user as possible. Nobody likes making accounts; nobody likes long surveys; nobody likes long load times. I wanted to get to the point and give the users what they came for – definitions, with no fluff. Inspired by Reddit’s outdated-but-straight-to-the-point design, I tried to cut out as much of this fluff as possible. Attention on the internet is precious, and a cute cat video is just a click away. My job was to eliminate any friction.
* * *
Six weeks later, I got to a point where the website was 99.5% done, and I knew I needed to launch it. I did 60% of the work in the first two weeks, and the last four were a mix of adding secondary features, obsessing over minor design elements, and not working with enough focus.
I knew I had to launch the site, because from here on, any further features would be dictated by my users. I had been avoiding this for weeks. James always suggested I was good at the “marketing” bit of things, but the truth is, I had no idea where to start. I did however, know that…
- my idea seemed to get good traction, which is why I set out to build it
- it’s better to have something out in the world with a few users than sitting in the drawer
- I needed to move on. I’d either be working on Hackterms a while longer, or it’d flop, and I’d move on to something else – but I needed to know
I was sure that more people would show up to the site looking for definitions than to add them, so I needed to seed the site with some starting definitions – and get others to, because I’m not qualified to teach the world to code – before announcing Hackterms to the world at large. Splitting the site into a soft launch stage and a hard launch would also allow me to effectively beta-test with anyone willing to try the site out.
I started with the low-hanging fruit. When I made my original reddit post, a whole bunch of users agreed to help. I reached out to them. I thought about their incentives, and what I could do to help motivate them – given my past work in crowdfunding, I thought about the best rewards. My contributors would be sacrificing their time, motivated by a desire to give back to the community. So, I needed to recognize their good motives. A small token, like a handwritten postcard, seemed like the easiest move (although that required getting the users’ addresses…). I also considered adding a badge to the site, but have always found these a little gimmicky. Finally, I knew I wanted to foster a sense of community amongst the contributors, so I started a Slack channel and created a subreddit, just in case.
I went back and re-read the Reddit thread, parsing 38 usernames of people who wanted to contribute. Next, I put together a Google doc of the top terms I’d want defined. A commenter suggested I use this roadmap as a starting point.
I was anxious to reach out to people. I thought of a dozen reasons Hackterms might fail; and of objections that people might raise to the site’s existence and purpose. I thought about the alternative resources available to developers: Wikipedia, StackOverflow, MDN, countless coding tutorials, FreeCodeCamp, you name it.
Nevertheless, I built Hackterms, and I believed in it, and Redditors thought this tool should exist. I had nothing to fear but the sting of rejection, and if I failed, well, at least I would have tried. I knew I’d be better off saying “I built something and put it out there” than “I built something and never went anywhere with it.”
I settled on a simple pitch – Hackterms was going to be the “why”, “where”, and “when” (importantly, not the “how”) of coding terminology. So, I took a deep breath, and reached out to the first 10 users.
About a month ago, I shared an idea for a dictionary of coding terms and you offered to help. Well, I’m excited to tell you that I’ve spent the last month building the site, and could now use your help!
In order to launch, we’ll need to have well-written seed definitions for common programming terms to attract initial users and get the ball rolling. Would you still be interested in creating an account and writing a few short definitions for common tools/concepts you use as a developer? Early users such as yourself will help set the tone and shape a direction for the site, and I’ll send you a vintage NYC postcard to thank you for your time (and swag down the road, if things go well!)
Let me know if you’re interested – hoping to work together on this!
* * *
I ended the day with just one user, but 6/10 (!) people responded positively. The next morning, I woke up to 3 users. The feeling of seeing people sign up for my thing – trust me with their accounts and their time – and seeing the supportive messages – is incredible. Users were also adding great definitions. I quickly threw together a metrics page to track how many users and definitions I was getting. I also had a few people join a Slack team I created. Messages like this kept me going, despite the fact that I was intimidated every step of the way by the fact that most contributors were probably way more knowledgeable than me. A scary thing about coding for me has always been that there are so many ways to do something, and I’ve always worried that the way I’m building isn’t the best or most correct way. Still,
Four or five days later, I was nearing 15 users and ~50 definitions, and had nearly exhausted my initial list of 38 redditors. I wasn’t sure how many to aim for, but wanted to fill the site with enough definitions for the most commonly searched terms before launching – perhaps 100? 200?
I made a few valuable observations, and it felt amazing to learn from users, not my own intuition.
- A bunch of new accounts only made one definition. Although I was approving them as quickly as possible (checking for new submissions incessantly), I thought that not immediately seeing their submissions must have turned these users off. James had suggested approving first and moderating later, so that’s what I did. I worked hard on my submission queue, but that didn’t matter. I turned it off, and auto-approved all definitions, at least while I could manage submissions.
- Users who added new definitions used the “related feature” field almost every time, and then followed these to add new definitions. They seemed to naturally follow a train of thought about a particular area of coding. I did this as well – I added “JSON”, and then “AJAX” followed naturally.
A week after that, I crossed 50 terms with almost 60 definitions. I also got a great code review and design pointers from my friend Esther. From here on, I knew I needed to generally refactor the code to avoid callback hell, add the ability to edit definitions, and most importantly – I needed more users.
UI, Take 3
But, I had gotten Hackterms off the ground. It was my first real user project since TheyGotFit, and it was live, and it was being used by real people – by strangers on the internet.
I stepped back and thought about getting more definitions, as well as a real public launch. More on that in Part II, hopefully soon.