Launching Your Own Ruby Gem (Part 2): Popularizing it Within the Ruby Community

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
• Promotion
• 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.

Repository README

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.

README structure

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 description - 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
• Authors
• License
• 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, .
• 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.

Contributing

 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 it outlines the way that contributors should behave when working with the code and other developers. In such a document you can write about the community standards and outline what behavior creates a positive environment and what behavior is unacceptable. You can also describe the project maintainers responsibility.

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:

• Reddit.com
• Rubyflow.com
• y.newscombinator.com
• digg.com
• Facebook groups
• LinkedIn groups
• dzone.com
• hacklines.com
• rubydaily.org
• ruby.libhunt.com 

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.

Organize contests

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.

Next steps

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!