In part 1 of this Launching Your Own Ruby Gem series, we went through a detailed tutorial building a gem for handling the ButterCMS API. Since software creation is only just the beginning, we will now dive further into the process of promoting our work and creating an active community around it.
There are many good Ruby gems out there but only some of them are very popular. Why? The answer is simple: the fact that something is good is not enough. It is our job to show the world our work, demonstrate how it works and encourage other people to get involved with the development process. Unfortunately, these days many developers create their libraries but then do nothing more. As a result, their work will slowly disappear among other developers’ code. Taking the next steps after launching your own Ruby gem is critical.
There are three important parts that we should focus on after creating our own Ruby gem:
- Great Documentation
- Active Community
Over the course of this article, I will focus on these three points, including real-world examples as reference for how you can accomplish each on your own.
Document Your Ruby Gem Well
Even if your Ruby gem is excellent, most people will not use it if you do not show them how to use it and demonstrate its power. Similar to tests, creating documentation slows down the process of creating software but lack of it may cause serious problems in the future - not only in the matter of usage but also in adding new features.
Documentation created automatically by RubyDoc
I am sure that you have heard many times that comments are an important part of the code and allow other developers to understand your work. No doubt about it. What is more, well-written comments allow you to automatically create documentation. The gem source that we created in the first part of this tutorial has a few examples:
- Ruby doc format: https://www.rubydoc.info/gems/butter_cms_v2
- Source: https://github.com/rubyhero/butter_cms
As you can see, Rubydoc can create documentation using your comments, but only if you are following the formatting rules. You can find these rules here: https://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md
This is the easiest and fastest way to create documentation for your gem - it does not require much effort and it formats the final documentation for you. It may be difficult to start writing such comments but the more you do it, the more it will become a habit and all your Ruby gems will have documentation from the beginning. However, for many people documentation created by the Ruby doc is still not the best place to start so we have to take care to implement a more human-friendly format.
Filling the README file with useful information is the best and most popular way of creating a place where other developers can start playing with your gem. A good README is like good clothes - even if someone has nothing to say, he may impress you with his style. On the other hand, even if someone is wise and has a lot to say you may not want to listen to him if his clothes are dirty. We very often judge the book by the cover and likewise, the gem by the README file.
The README file should contain only the most important information. Reading the file contents should give a user a general overview of the gem usage, libraries used in the project, gem authors and ways of contributing.
We can break down a good README template into the following sections:
- Project title and
shortdescription - Project description should be meaningful and should not be longer than one paragraph.
- Getting started - Tell the user how he can get a copy of the project up and running on his local machine for development and testing purposes. You can add two subsections here: Prerequisites and Installing
- Deployment - Add notes on how to deploy the code on the live system
- Built with - List the external libraries used in the project
- Contributing - Information about the ways that users can contribute to the project, link to the code of conduct document and the process of submitting pull request to the repository
- Versioning - Information about available versions
- Acknowledgments - Thank anyone whose code was used or anyone who inspired you to build the gem
Get an attractive look
As we mentioned a few paragraphs earlier, we judge a book by its cover so having great content is not enough. Give your README brand new attire:
- Text formatting - Familiarize yourself with the markdown syntax and use proper headers, paragraphs, and lists for the gem instructions. Having a great structure of headers allow user to quickly go through the whole file and get clues about the project without diving into the details.
- GIF animations - GIFs are great for memes but we can also use them to show the user how he can use our library. Quick animations can be a perfect spacer for longer text. There are some free tools for GIF creation available out there: Giphy Capture, LICEcap,
Recordit and ttystudio.
- Personalize your README - Invest some time making the logo for your Ruby gem, upload it somewhere on the internet and include it in your readme.
Contribution instructions and code of conduct
This information can be part of the README but you can also extract it to a separate file and leave a proper link under the Contributing section header.
Describe the pull request process. You can include the following information:
- The way that the issue should be discussed before working on fixing it
- The gem version incrementation process
- The merge policy - who and when they can merge your changes
Code of conduct
The code of conduct is a set of rules outlining proper practices. In the case of the gem
Dedicated website for the documentation
Creating a dedicated website for documentation is the most flexible solution, but it also requires more work than the previous two documentation types. If your gem is simple and using it does not require any further knowledge, then it is recommended to put the information into a README or use wiki pages on your repository website. If your tool does a lot of things and using it requires more knowledge, then a dedicated website may be the best idea.
You can build your own app to display documentation but you can also use tools that will do the work for you. VuePress is one of such tools, it supports Markdown and extends it with some cool features like alert boxes and automatically generated navigation. If you don’t want to use your own servers for the documentation, GitBook might be the best choice for you. It’s also free for open source projects.
Promote Your Ruby gem
You can create an awesome gem and write an excellent README but without the proper promotion, nobody will know about your library. If you have expansive social network accounts on Twitter or Facebook, it will be easier but even without them you can reach many people potentially interested in using your solution.
Solve real problems
If your gem solves an existing issue, you can find people on Twitter that were complaining about this issue and let them know that your gem can help them. Don’t be intrusive but join discussions and focus on providing value and help rather than spamming with links to your gem repository.
Places to promote articles and tutorials
If you are writing your own articles on your own blog or as a guest you can create one showing how to use your gem in a practical way. Then, to show it to a larger audience, you can post it on the following Ruby-related networks:
- Facebook groups
- LinkedIn groups
Ruby community newsletters
Writing a useful article about your library and sharing it using the networks mentioned above is the easiest way to be mentioned in Ruby newsletters. The most popular are Ruby Weekly, Ruby Daily and Awesome Ruby. Being mentioned in these newsletters means that you will reach thousands of users interested in Ruby code and fresh gems that are ready to solve common issues.
If you are not noticed by the newsletter authors and you are sure that your content will be very helpful for the community, you can reach them directly via e-mail or twitter and let them know about your article or tutorial.
Conferences and meetings
If you are a speaker or you are ready to get out of your comfort zone, you can go to the local Ruby meetings or bigger tech conferences and tell people about your gem. Sometimes, reaching people directly may produce awesome results because they can share your work on their social networks.
Build an active and engaged community
An active and engaged community is fundamental for any open source project. Thanks to it your gem will grow, people will report issues, and they will help you fix them. As your community grows, you have to take care of your community members: constantly stimulate them and show them your appreciation. It seems hard at first sight, but there are tested ways of doing this:
Stick to one communication channel
Well maintained communication between library developers and people who use the library is one of the most important things. It’s not easy, but it might be easier if you decide to stick to only one communication channel. Which one? It depends on your needs. The most popular choices are mailing lists, forums and chats. These days Slack seems to be the best option to communicate with your community because it supports many channels and nested threads and it provides many ways of extending the base functionality of the chat with bots.
People like to compete and you have to show your community that great things can be created with your gem. Why not create a contest? Developers can build small applications using your solution and show their skills to the larger audience.
Build your tribe
Your Ruby gem is your brand. If you want to build your own tribe of people who identify with your software, you have to give them a chance. Stickers and t-shirts are great incentives and allow other developers to manifest appreciation for your library. It might be a more expensive option, but it will eventually pay off and give you that unique feeling when someday you see someone with your logo on their chest or laptop during an event.
Look outside the open source
Contributing to the open source is great but doing things for business clients is also very valuable and helps your solution and community to rapidly grow. Yes, you can do both at once. Sidekiq is the best example here. Its author provides three versions of his gem where the first one is free and it's super useful. Thanks to the paid versions he can spend more time on developing Sidekiq's code which results also in better quality for the open source world. Consider going into this direction to make your solution more stable in case of quality, growth and funds for the future development.
Show your appreciation
Everyone needs appreciation. Especially when talking about open source volunteers who help you maintain your repository and accelerate the growth of your tool. It is a good idea to create some kind of board where it will be possible to see the most active developers. Maybe it is worth it to choose one developer each month and write about him or her on the library’s blog.
You created a useful gem, prepared documentation and built an active community around it. It’s still just the beginning. It’s now time to improve your solution, accept improvements from the community and look for new ways to grow. Remember to constantly engage and promote your own Ruby gem through different channels.
Incase you missed it, you can read part 1 of of this Launch Your Own Ruby Gem series here. Stay tuned for more!