In this post, Software Engineer at AYLIEN, Afshin Mehrabani talks us through his experience in building and launching an incredibly popular open source library called Intro.js.
4 years ago, when I started Intro.js as a weekend project I knew it was a useful idea but I didn’t expect to eventually have the likes of Microsoft, IBM, SAP and Amazon using what I had built.
In this post I’ll talk about what sparked the idea for Intro.js, why I open sourced it and what I have learned in the process.
I originally started Intro.js to use it on a particular product I was working on at the time. I was working as part of a web development team building web-based stock exchange software. The system had many user facing components, tools and widgets and it was a little confusing to use. This meant the support team we worked with spent most of their time on phone calls guiding people on how to use the software, find options, complete trades etc. instead of dealing with the bugs and issues our users had.
Things got even worse when we completely changed the user interface. The support team were working almost exclusively on user interface-related queries and were spending a lot of time guiding users through critical workflows. As you can imagine our support answering the same questions and running thousands of customers through a guided tour just wasn’t efficient.
As a part of the development team, we had to ensure the UI/UX was kept simple and straightforward enough for users to understand the workflow. Which I know is a common problem in software design, but for some web-based portals like this one, it’s an almost impossible task.
Imagine the UI for stock exchange software, it’s made up of many critical moving parts that are paramount to not just the users experience but the software carrying out the job at hand.
Financial software example – source: www.metatrader4.com
These UI’s are busy and complicated and for the most part they need to be. If an object is included in the UI it’s critical to the job at hand. You can’t eliminate any objects from the page and you still need to make it clear enough for users to interact with.
The pictures below illustrate some sample steps of a simple Intro.js guide, with the highlighted component, a description of the step and control buttons.
Through the control buttons a user can decide to go to the next step, previous step or close the guide.
Although a relatively simple idea after implementing the original version of Intro.js on that project, I realised what I had built could benefit a lot of people who were facing the same problem we had. Which is why I decided to open-source it and let the community use and add to it while of course making some improvements to the code base.
I have now open-sourced almost all of the useful components I built. Not only has this helped a lot of people save time and money, but we’ve also built an active and vibrant community around Intro.js who help maintain the project, add more features, fix bugs and everything else that needs to be done.
In the last year, I have been building on the original offering. Most recently adding the Hints feature. Using this feature, you can add clickable circles to different elements of the webpage with extra descriptions:
Bringing it to the masses
So I had built and validated my idea in a live project and I was pretty sure there was demand out there for something like Intro.js but the challenge was how would I get this into the hands of other developers.
The open source community
After releasing the first version of Intro.js, I created a simple HTML page to demonstrate what it does. I suppose I didn’t think too much about how I was going to find users but I knew from already being actively involved in the open source community that if something was truly useful it would spread and gather pace through the community eventually. I had no idea though that within a couple of days I’d be struggling to keep up with the demand.
To try and get some exposure I decided to submit a post on Hacker News as well as some other dev focused outlets none of which had the effect of Hacker News. Within a couple of hours of the post going live it was gathering some serious interest. Over a couple of days days the post had received about 800 upvotes, 160 comments and the post was on the homepage of Hacker News for two consequent days.
During these two days, I got about 100 pull requests merged and after a month released some other minor versions to address the initial version issues and bugs.
Intro.js was a real hit and I never expected the interest it gathered from users and the hard work of other developers who helped the project by fixing issues, adding features and writing plugins for Angular.js, React, jQuery, etc. However, in saying that, it still probably took about a year to release a stable version of Intro.js that I was happy with.
Since the launch we’ve had some really great companies and developers using Intro.js, it’s been featured on some pretty cool blogs and outlets like Sitepoint and IBM developer works and has collected nearly 15,000 stars on Github.
Maintaining an open-source project
Things get more complicated when you have many many users. You have to be responsible for the product you provide, answer questions, maintain code, merge pull requests all while also adding more features to the library.
Juggling an open source project, my job at AYLIEN ( we’re hiring BTW 😉 ) and also a Masters course at the university became increasingly difficult and finding new maintainers to work with has also proven quite difficult. Which meant to keep Intro.js alive I needed to look at what options were available.
I was unable to devote all of my time to develop and maintain an open-source project. It was clear I needed to hire some more people, mainly web developers, to work on customer queries, fix issues and maintain the project.
Which is why I decided to add a commercial license to Intro.js. I was reluctant to do so in the beginning but after some careful consideration, I’m glad I did. This decision has helped the project a lot; the codebase has improved significantly since, we can now properly serve our users and we can invest more time in adding more features and keeping our users happy.
Adding a commercial license to an open-source project motivates the creators and the maintainers to keep developing the project and release more awesome, useful versions. Since moving to a commercial license we have added a documentation section using Doc42 and moved the Markdown files from Github to introjs.com/docs. Moreover, Intro.js now has an active tag on StackOverflow where developers can tag their questions with Intro.js and get the answer from the awesome community.
Note: There are many open-source licensing options available. You can read more about them here.
We are going to release v3.0 soon which will add responsive tours and many more features. Meanwhile, we are fixing more issues and bugs and v2.5.0 will be released in the next two weeks.
I have learned a lot more than I have could have imagined by building and maintaining a real open-source project, I have gained invaluable experience in answering user queries, releasing versions, licensing products and so on and for that reason alone I can say for sure that open sourcing the project was the best decision I made.
Intro.js was a weekend project that turned into a real product and I hope this post gives you the push to go and build something yourself and contribute to the movement or better still to open source something you’ve already built that you think appeals to the masses. Publishing and releasing the first stable version of an open-source project could take you more than a year but during this process, I promise you, you will learn a lot and you’ll have a lot of fun doing it and who knows, you may even get a nice Thank You email from a tech giant ;).