Your repository pages are where your users make a decision to buy a subscription to your repository. Using your README file and setting a good description can make a huge difference in your subscribers count.
When you use xs:code, you keep two repositories: A public repository that is visible to the public on Github, and another private repository, that is only visible to users visiting your repository page on xs:code. Note that your readme file and repository description on your private repository are visible to all xs:code users, even if they haven't subscribed yet, making it the most critical part in users' decision to subscribe to your repository.
Because your repository description is seen before your readme file, you should include a concise summary of what your repository does, to help users understand quickly when searching.
On the public repository's description, it's also important to include a brief message about your paid repository, and what is offered there. For example, if your paid version offers a permissive license, your description should look similar to this:
<repository name> is a JS library to assist with front-end operations on mobile browsers. An MIT licensed version is available on xscode.com.
If your paid version offers added functionality, your should specify that instead:
<repository name> is a JS library to assist with front-end operations on mobile browsers - Android only. iOS support is available on xscode.com.
The description on your private (paid) repository can be more concise:
<repository name> is a JS library to assist with front-end operations on mobile browsers. MIT licensed version.
Or in the other case:
<repository name> is a JS library to assist with front-end operations on mobile browsers. Android & iOS support included.
The README file
Your readme file is the key source for information about your repository. You should include as much information about your code, how to use it, and other useful details. These important point should always be included in your readme file:
Project title and description
Include a unique name and information about what your code does. Be as detailed as possible, without getting too technical. Use the documentation section for more technical information.
Monetization and licensing information
It's important to let your users know as soon as possible, that your are monetizing your repository. Depending on the monetization path your chose (For example dual licensing, or open-core), you should include the relevant information.
For example, if you are using dual licensing, you public repository (typically licensed with GPL), consider including a section like this:
This repository is offered with a dual licensing model. The version offered here, is GPL licensed, and an MIT version is available as a paid subscription on xs:code, <add your xs:code repository URL here>
If you are using the open-core model, and offer additional features on your private repository, consider adding this:
This repository is offered as open-core. The basic functionality of <add your basic functionality> is available for free here. Additional features such as <add a list of features included in the paid version> are available as a paid subscription on xs:code, <add your xs:code repository URL here>
Include everything your users will need prior to installing or integrating your project.
Provide detailed information on how to install or integrate your project.
Write down a list of all the features and functionality your project offers. It will make it easier for users to understand the specific value your project has for them.
Proper documentation is key to get as many people as possible using your project. Consider that the more details and information you include in your documentation, the more likely are users to find value in your project, making them more likely to become paying users. Keeping your documentation up to date is also crucial for keeping your subscribers happy and paying.
Include an "Author" section, with any means of communications you wish to give your users. The easier it is to contact you, the more likely users are to use your project.
Also, consider also adding these useful sections:
- Static code analysis - Make it easy for users to see the project progress and many other indicators, include badges of other platforms and donations. Check out Shields.io (badges/shields) to use or make your own badges.
- Graphics - Adding attractive, eye-catching graphics, is a great way to attract attention and show that there is someone behind your project that is willing to spend the time and efforts to support it. If you don't have graphic design skills, you can outsource it to other services such as fiverr or upwork.
- Visual demo - If you project has a visual side, UI or any front end elements, an animated/video demo of how it works does wonders in getting your users to subscribe.
- Built With - Show the framework you're using, dependencies and RSS Feeds
- Links -It's good to include a summary of the most useful links to developers using your project.
- Contributors Credits - Credit and add a list of your contributors.
- Support & Maintenance offers - If you intend to offer additional services in your paid repository, be sure to include them both on your public and your private repositories, and clearly state that paying users only will be entitled to what you are offering. Be as specific as possible with what is included and not in your offer.
If you intend on accepting contributions from others, be sure to include your contribution guidelines here, or on a separate CONTRIBUTING file. If you're using a dual licensing model, note that there are requirements before you can accept contributions to a copyleft licensed code. Refer to our dual licensing guide for more information.
Some more resources
- A list of great README examples: matiassingers/awesome-readme
- A README Generator: kefranabg/readme-md-generator
Need our help? You got it!
We are here to help you take your project to the next level and get more paying users. Need help with promoting your project? Our community team is here to help.
Talk to our community experts and they’ll do their best to help you boost your project to the stars: firstname.lastname@example.org