Dark devlog #3: onboarding

Dark devlog #3: onboarding

An annoying thing about coding is that some days you're on fire, producing masterpieces, knocking down obstacle after obstacle. And some weeks, you're trapped figuring out bugs that ultimately come down to having a semi-colon out of place.

Most of the time for me, the difference between the two is the amount of context I have in the codebase, and the amount of technical debt that has been built up.


So this week I've been working on onboarding, and it's been a time of building up context on a repo I'm not familiar with, as I wade through technical debt.

The signup flow for Dark was interesting. You would sign up by adding your email address via a form on darklang.com. That form is served by the ops-corpsite canvas, and when you add your email you get added to a Mailchimp mailing list, and you get sent to one of two pages: if you have a signup token, you go to /signup, otherwise you go to /beta.

The beta workflow is the one we've used the most: it asks you questions intended to figure out how serious you were, so that we could do some triaging and customer interviews to make sure we understood what people used Dark for. This was helpful when we were in the early days. Potential beta users were added to an Airtable where we'd figure out the best users and email them via a form built using the ops-adduser Dark canvas.

Are you lost yet? We've barely started.

Users who replied with their desired username got added as users, which meant we'd fill out a form pointing to a little app we built in Dark. We'd auth with our personal gmails so that users would get a person email from our gmail when they were added. The app would also add them to the Slack community, move them to a different column in Airtable, send a handful of emails (via Mandrill via Mailchimp), send a Slack message to our Slack, and also a handful of things like tracking in Heap/Segment.

All built in Dark, including homegrown error tracking tool in Dark as well.

Of course, that's only one path. If you got sent to /signup you'd get to actually sign up. We'd check the token you were using was valid, and that the username wasn't taken (we expose some of the internals of Dark to certain admin canvases so that we can build non-essential tooling in Dark, such as this). You'd then be added to the app, and we'd inform Auth0 that we'd done so. Then you'd get an email telling you go to back to darklang.com, where you'd click Login, then click Login again, then click "Forgot password", then wait for an email and click on the link, then  change your password, and then hopefully log in.

Not a great experience.

Of course, after that you'd be presented with a blank screen and have no idea what to do, and invariably you'd wander off. In the last few months we added tutorials and samples, so that at least you have some idea what to do, even though they're not great yet.

So I spent most of this week understanding and detangling this flow, which spans three dark canvases, 3 different codebases, and at least 6 different services/vendors. When you have 3-4 people involved in managing a user sign up flow, the complexity builds up, and while those complexities provide value, that value doesn't hold when there's just one of me. So I removed the vast majority of this, and made it so you could just sign up. That shipped on Friday, and it seems like 20-ish people have signed up since then.

I haven't announced it yet because the onboarding experience isn't good yet (you still, for example, have to go through the "forgot password" flow), and I still have to add analytics to understand what's actually happening (I don't know how many of the 20 got further, for example).

I've also spent time making it easier to learn about Dark, mostly by pointing everything at everything else; for example, you can now find most of our content from the footer of either darklang.com or darklang.com/docs. We have a wealth of video tutorials and doc tutorial and samples, which were not really linked from anywhere, and I plan to add those to within the app as well.

So slow but steady progress on onboarding.


The contribution front is going pretty well. Most of the Changelog this week comes from contributors, with stellar work from Brian Chen and David Cooley.

David Cooley also made an excellent point about how people can contribute - if right now they have to learn OCaml they're not going to contribute as much as they would if they were able to contribute in Dark.

We've got the first inaugural Dark contributor meetup this Friday (you're welcome to join, even -- or especially -- if you haven't contributed yet). It's via zoom of course, as we're not monsters, and so far about 16 people are coming.

My hope is to figure out how we can enable more Dark users to contribute, so a lot of the conversation will be centered around things like the package manager and enabling contributions that can be written in Dark.

You can sign up for Dark here, and check out our progress in these features in our contributor Slack or by watching our GitHub repo. Comment here or on Twitter.