By clicking “Accept all”, you agree to the storing of cookies on your device to enhance site navigation, analyze site usage, and assist in our marketing efforts. View our Cookie Policy for more information.
Documentation is the backbone of any successful open-source project. It not only serves as a guide for developers and users but also acts as a vital marketing tool for attracting new users. However, many developers make the common mistake of using their GitHub repository as the primary source for documentation. In this blog, we will explore the limitations of using GitHub as your primary documentation source and the benefits of using your own docs site for hosting your project's documentation.
Using your GitHub Repo as your Primary Documentation Source: Limitations
You may think that using your GitHub repo for your documentation is a quick and easy solution, but you may be missing out on a lot of benefits that building your own docs site can offer. Your GitHub repo has several drawbacks that can affect your documentation quality and user satisfaction. Here are some of them:
It has poor formatting and styling options. It only supports Markdown, which is a simple markup language that can create basic text formatting. However, it cannot create more advanced and attractive content, such as interactive elements, custom fonts, colors, or layouts.
It has limited media and asset support. It only allows you to embed images and links in your documentation. You cannot include other types of media, such as videos, tutorials, or code examples, that can make your documentation more engaging and helpful for your users.
Using GitHub for docs is easy but suboptimal. Building your own docs site can provide your users of better quality documentation and an optimized user experience.
Documentation as Your #1 Marketing Tool
When you create an open-source project, you want to share it with the world and get more people to use it and contribute to it. But how do you convince them that your project is worth their time and attention? How do you make a good first impression and build trust and loyalty with your users? The answer is documentation.
Documentation is more than just a technical guide; it is also a powerful marketing tool for your open-source project. It is the first thing that potential users will see when they visit your project’s website or repository. It is the way you communicate your project’s vision, purpose, features, and benefits to your audience. It is the way you show your project’s personality and brand identity, and how you integrate it with your main website.
By building your own docs site for your project’s documentation, you can create a user-friendly and branded experience that showcases your project in the best possible light. You can customize the look and feel of your documentation to match your project’s style and tone. You can use images, logos, colors, fonts, and layouts that reflect your project’s identity and values. You can also link your documentation to your main website, social media accounts, or other relevant platforms, creating a seamless and consistent user journey.
Embracing Interactivity and Rich Media
One of the advantages of using your own docs site for your documentation is that you can add interactivity and rich media to your content, which can enhance the user experience and learning outcomes. Interactivity and rich media can help you:
Capture the user’s attention and interest with engaging visuals and sounds.
Explain complex concepts and processes with clear and concise demonstrations and examples.
Provide feedback and guidance to the user with interactive tools and exercises.
Encourage the user to explore and experiment with your project’s features and functionalities.
By building your own docs site, you can embed various types of interactivity and rich media into your documentation, such as videos, conference talks, tutorials, and code examples directly into your documentation, making it a more engaging and valuable resource for your audience.
Interactivity and rich media can enhance your open source project documentation by engaging the user, demonstrating concepts, guiding the user, and stimulating exploration.
Utilizing Two Decades of Web Knowledge
The web has evolved tremendously over the last two decades, and so has our understanding of how to create effective and user-friendly websites. By using your own docs site for your documentation, you can leverage this web knowledge and apply it to your documentation website, creating a better experience for your users and yourself. Here are some of the benefits of using your own docs site in terms of web knowledge:
Optimized navigation: Building your documentation site allows you to create a clear and intuitive navigation system for your documentation, making it easy for your users to find what they are looking for. You can use menus, tabs, breadcrumbs, or other navigation elements to organize your documentation into logical sections and sub-sections. You can also use internal links to connect related pages or topics within your documentation, creating a coherent and consistent flow of information.
Enhanced searchability: Building a site for your documentation enables you to improve the searchability of your documentation, both internally and externally. Internally, you can use a search box or a search engine plugin to allow your users to search for keywords or phrases within your documentation, saving them time and effort. Externally, you can use SEO (Search Engine Optimization) techniques to increase the visibility and ranking of your documentation website on popular search engines like Google or Bing, attracting more traffic and potential users to your project.
Detailed analysis: Having your own docs site provides you with access to various analysis tools that can help you understand your users’ behavior and needs better. Some of these tools are: ◦ Scarf: A privacy-preserving analytics platform that tracks how your documentation website is used and by whom. You can use Scarf to measure the number of visitors, page views, bounce rate, average time spent, most popular pages, etc. You can also use Scarf to identify the organizations and companies that are using your documentation website, and how they are using it. ◦ Google Analytics: A widely used web analytics service that tracks and reports website traffic. You can use Google Analytics to measure the performance of your documentation website, such as the user acquisition, behavior, and conversion rates. You can also use Google Analytics to segment your users by various criteria, such as location, device, browser, etc. ◦ Matomo: A free and open source web analytics platform. Matomo is a great alternative to Google Analytics if you want to have full control over your own data and avoid sharing it with third parties. You can also use Matomo to create custom reports and dashboards that suit your needs. ◦ Mixpanel: A user analytics platform that helps you understand how your users interact with your documentation website. You can use Mixpanel to track the actions and events that your users perform on your documentation website, such as clicking a button, downloading a file, or completing a form. You can also use Mixpanel to create funnels, cohorts, and retention reports that show how your users progress and engage with your documentation website.
By using these analytics tools, you can gain a comprehensive and holistic understanding of your users’ behavior and needs. You can also use feedback forms, surveys, or comments to collect direct feedback from your users, learning about their satisfaction, preferences, or suggestions for improvement.
By building a site for your documentation, you can utilize two decades of web knowledge and best practices to create a more effective and user-friendly documentation website.
Catering to Different User Preferences
One of the main goals of any open-source project is to get more users and contributors to join and support your project. However, this can be challenging if your documentation is not appealing or accessible to a wide range of users. Different users may have different preferences, needs, or expectations when it comes to documentation. How do you create documentation that satisfies and attracts all kinds of users?
The solution is building your own docs site. This allows you to create an interactive static-generated site that can cater to different user preferences and increase the adoption of your open-source project.
The Solution
The best way to create your own docs site is to use a static site generator (SSG) such as Hugo, Docusaurus, Doscify, and so on. These tools allow you to build your docs site from your own repository and host it on a platform like Github Pages, Read the Docs, or any other service of your choice.
There are many alternatives for storing your documentation off GitHub, depending on your budget, skills, and requirements. Here are some of the most popular ones:
Read the Docs: Read the Docs is a free and open source platform that hosts documentation for thousands of open source projects. It supports various formats like Markdown, reStructuredText, AsciiDoc, and Sphinx, and integrates with GitHub, GitLab, Bitbucket, and other version control systems. It also provides features like versioning, translations, search, PDF export, custom domains, and analytics.
GitBook: GitBook is a paid platform that lets you create beautiful and interactive documentation from Markdown files. It integrates with GitHub and other version control systems, and provides features like collaboration, comments, search, custom domains, analytics, and more.
Docusaurus: Docusaurus is a free and open source static site generator that helps you create documentation websites from Markdown files. It integrates with GitHub and other version control systems, and provides features like versioning, translations, search, custom themes, plugins, and more.
MkDocs: MkDocs is another free and open source static site generator that helps you create documentation websites from Markdown files. It integrates with GitHub and other version control systems, and provides features like themes, plugins, search, navigation, custom domains, and more.
Read the Docs is a free platform that hosts documentation for open source projects, supports various formats and integrations, and offers features like versioning, translations, and analytics.
Building your own documentation site is the perfect solution to convert your static documentation into an interactive, dynamic, and user-friendly website. With your own docs site, you can maintain the simplicity of Markdown while adding powerful features like embedded coding tools, examples, and training modules.
Combining Scarf Analytics with Your Documentation Site
You have seen how building your own documentation site can help you create and host your project’s documentation with ease and efficiency. But what if you want to know more about who is using your documentation and software, and how they are using it? That’s where Scarf comes in. Scarf is a powerful platform that tracks and analyzes how your documentation website and software are used and by whom. It can provide you with valuable data and insights that can help you improve your project and reach more users. In this section, we will show you how to integrate Scarf Gateway with your docs site and how this combination can take your open-source project to the next level.
Understanding Scarf Analytics
Scarf Gateway acts as a bridge between your users and the current distribution channels of your software. The installation and deployment methods remain unchanged, ensuring a seamless user experience. What sets Scarf apart is its ability to collect metadata and non-personal identifiers from various sources, including downloads, documentation views, and installations. This data is invaluable in understanding user behavior, engagement, and preferences.
Tracking Documentation Views and Downloads
With Scarf Gateway integrated into your own documentation site, you gain a comprehensive view of user interactions. By tracking documentation views, you can understand which sections of your documentation are most popular and which might require improvement. Additionally, tracking downloads provides insights into the popularity and reach of your software.
User Behavior and Adoption Insights
Scarf Gateway enables you to see how users utilize your software and documentation. Understanding user behavior within your documentation can help you identify pain points and areas where users may struggle. Armed with this knowledge, you can make targeted improvements to enhance the overall user experience.
Identifying User Origins and Represented Companies
One of the most powerful aspects of Scarf Gateway is its ability to identify where your users come from and the companies they represent within your community. This information can be crucial for understanding your project's reach and the impact it has on various industries. By knowing who your users are, you can tailor your documentation and software to better meet their needs.
Optimizing Documentation and Software Strategy
The combination of Scarf and your self-hosted docs site empowers you to make data-driven decisions. Utilize the insights gained to optimize your documentation and software strategy. Tailor your content to target specific user segments, improve areas that require attention, and align your project's goals with the needs of your community.
Fostering Community Engagement
The data collected by Scarf can help you identify active contributors and influential users within your community. Recognizing and engaging with these individuals can foster a stronger sense of community and encourage further collaboration.
Conclusion
In conclusion, using GitHub Repositories as the primary source for your project's documentation can limit its growth and adoption potential. Building your own documentation site allows you to optimize your user experience, integrate your brand's personality, and leverage valuable web knowledge to create a compelling, interactive, and user-friendly documentation hub. As open-source projects continue to thrive on collaboration and community support, investing in high-quality documentation through your self-hosted docs site will undoubtedly prove to be a game-changer for your project's success. So, why settle for less?
This is some text inside of a div block.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse varius enim in eros elementum tristique. Duis cursus, mi quis viverra ornare, eros dolor interdum nulla, ut commodo diam libero vitae erat. Aenean faucibus nibh et justo cursus id rutrum lorem imperdiet. Nunc ut sem vitae risus tristique posuere.
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Documentation is the backbone of any successful open-source project. It not only serves as a guide for developers and users but also acts as a vital marketing tool for attracting new users. However, many developers make the common mistake of using their GitHub repository as the primary source for documentation. In this blog, we will explore the limitations of using GitHub as your primary documentation source and the benefits of using your own docs site for hosting your project's documentation.
Using your GitHub Repo as your Primary Documentation Source: Limitations
You may think that using your GitHub repo for your documentation is a quick and easy solution, but you may be missing out on a lot of benefits that building your own docs site can offer. Your GitHub repo has several drawbacks that can affect your documentation quality and user satisfaction. Here are some of them:
It has poor formatting and styling options. It only supports Markdown, which is a simple markup language that can create basic text formatting. However, it cannot create more advanced and attractive content, such as interactive elements, custom fonts, colors, or layouts.
It has limited media and asset support. It only allows you to embed images and links in your documentation. You cannot include other types of media, such as videos, tutorials, or code examples, that can make your documentation more engaging and helpful for your users.
Using GitHub for docs is easy but suboptimal. Building your own docs site can provide your users of better quality documentation and an optimized user experience.
Documentation as Your #1 Marketing Tool
When you create an open-source project, you want to share it with the world and get more people to use it and contribute to it. But how do you convince them that your project is worth their time and attention? How do you make a good first impression and build trust and loyalty with your users? The answer is documentation.
Documentation is more than just a technical guide; it is also a powerful marketing tool for your open-source project. It is the first thing that potential users will see when they visit your project’s website or repository. It is the way you communicate your project’s vision, purpose, features, and benefits to your audience. It is the way you show your project’s personality and brand identity, and how you integrate it with your main website.
By building your own docs site for your project’s documentation, you can create a user-friendly and branded experience that showcases your project in the best possible light. You can customize the look and feel of your documentation to match your project’s style and tone. You can use images, logos, colors, fonts, and layouts that reflect your project’s identity and values. You can also link your documentation to your main website, social media accounts, or other relevant platforms, creating a seamless and consistent user journey.
Embracing Interactivity and Rich Media
One of the advantages of using your own docs site for your documentation is that you can add interactivity and rich media to your content, which can enhance the user experience and learning outcomes. Interactivity and rich media can help you:
Capture the user’s attention and interest with engaging visuals and sounds.
Explain complex concepts and processes with clear and concise demonstrations and examples.
Provide feedback and guidance to the user with interactive tools and exercises.
Encourage the user to explore and experiment with your project’s features and functionalities.
By building your own docs site, you can embed various types of interactivity and rich media into your documentation, such as videos, conference talks, tutorials, and code examples directly into your documentation, making it a more engaging and valuable resource for your audience.
Interactivity and rich media can enhance your open source project documentation by engaging the user, demonstrating concepts, guiding the user, and stimulating exploration.
Utilizing Two Decades of Web Knowledge
The web has evolved tremendously over the last two decades, and so has our understanding of how to create effective and user-friendly websites. By using your own docs site for your documentation, you can leverage this web knowledge and apply it to your documentation website, creating a better experience for your users and yourself. Here are some of the benefits of using your own docs site in terms of web knowledge:
Optimized navigation: Building your documentation site allows you to create a clear and intuitive navigation system for your documentation, making it easy for your users to find what they are looking for. You can use menus, tabs, breadcrumbs, or other navigation elements to organize your documentation into logical sections and sub-sections. You can also use internal links to connect related pages or topics within your documentation, creating a coherent and consistent flow of information.
Enhanced searchability: Building a site for your documentation enables you to improve the searchability of your documentation, both internally and externally. Internally, you can use a search box or a search engine plugin to allow your users to search for keywords or phrases within your documentation, saving them time and effort. Externally, you can use SEO (Search Engine Optimization) techniques to increase the visibility and ranking of your documentation website on popular search engines like Google or Bing, attracting more traffic and potential users to your project.
Detailed analysis: Having your own docs site provides you with access to various analysis tools that can help you understand your users’ behavior and needs better. Some of these tools are: ◦ Scarf: A privacy-preserving analytics platform that tracks how your documentation website is used and by whom. You can use Scarf to measure the number of visitors, page views, bounce rate, average time spent, most popular pages, etc. You can also use Scarf to identify the organizations and companies that are using your documentation website, and how they are using it. ◦ Google Analytics: A widely used web analytics service that tracks and reports website traffic. You can use Google Analytics to measure the performance of your documentation website, such as the user acquisition, behavior, and conversion rates. You can also use Google Analytics to segment your users by various criteria, such as location, device, browser, etc. ◦ Matomo: A free and open source web analytics platform. Matomo is a great alternative to Google Analytics if you want to have full control over your own data and avoid sharing it with third parties. You can also use Matomo to create custom reports and dashboards that suit your needs. ◦ Mixpanel: A user analytics platform that helps you understand how your users interact with your documentation website. You can use Mixpanel to track the actions and events that your users perform on your documentation website, such as clicking a button, downloading a file, or completing a form. You can also use Mixpanel to create funnels, cohorts, and retention reports that show how your users progress and engage with your documentation website.
By using these analytics tools, you can gain a comprehensive and holistic understanding of your users’ behavior and needs. You can also use feedback forms, surveys, or comments to collect direct feedback from your users, learning about their satisfaction, preferences, or suggestions for improvement.
By building a site for your documentation, you can utilize two decades of web knowledge and best practices to create a more effective and user-friendly documentation website.
Catering to Different User Preferences
One of the main goals of any open-source project is to get more users and contributors to join and support your project. However, this can be challenging if your documentation is not appealing or accessible to a wide range of users. Different users may have different preferences, needs, or expectations when it comes to documentation. How do you create documentation that satisfies and attracts all kinds of users?
The solution is building your own docs site. This allows you to create an interactive static-generated site that can cater to different user preferences and increase the adoption of your open-source project.
The Solution
The best way to create your own docs site is to use a static site generator (SSG) such as Hugo, Docusaurus, Doscify, and so on. These tools allow you to build your docs site from your own repository and host it on a platform like Github Pages, Read the Docs, or any other service of your choice.
There are many alternatives for storing your documentation off GitHub, depending on your budget, skills, and requirements. Here are some of the most popular ones:
Read the Docs: Read the Docs is a free and open source platform that hosts documentation for thousands of open source projects. It supports various formats like Markdown, reStructuredText, AsciiDoc, and Sphinx, and integrates with GitHub, GitLab, Bitbucket, and other version control systems. It also provides features like versioning, translations, search, PDF export, custom domains, and analytics.
GitBook: GitBook is a paid platform that lets you create beautiful and interactive documentation from Markdown files. It integrates with GitHub and other version control systems, and provides features like collaboration, comments, search, custom domains, analytics, and more.
Docusaurus: Docusaurus is a free and open source static site generator that helps you create documentation websites from Markdown files. It integrates with GitHub and other version control systems, and provides features like versioning, translations, search, custom themes, plugins, and more.
MkDocs: MkDocs is another free and open source static site generator that helps you create documentation websites from Markdown files. It integrates with GitHub and other version control systems, and provides features like themes, plugins, search, navigation, custom domains, and more.
Read the Docs is a free platform that hosts documentation for open source projects, supports various formats and integrations, and offers features like versioning, translations, and analytics.
Building your own documentation site is the perfect solution to convert your static documentation into an interactive, dynamic, and user-friendly website. With your own docs site, you can maintain the simplicity of Markdown while adding powerful features like embedded coding tools, examples, and training modules.
Combining Scarf Analytics with Your Documentation Site
You have seen how building your own documentation site can help you create and host your project’s documentation with ease and efficiency. But what if you want to know more about who is using your documentation and software, and how they are using it? That’s where Scarf comes in. Scarf is a powerful platform that tracks and analyzes how your documentation website and software are used and by whom. It can provide you with valuable data and insights that can help you improve your project and reach more users. In this section, we will show you how to integrate Scarf Gateway with your docs site and how this combination can take your open-source project to the next level.
Understanding Scarf Analytics
Scarf Gateway acts as a bridge between your users and the current distribution channels of your software. The installation and deployment methods remain unchanged, ensuring a seamless user experience. What sets Scarf apart is its ability to collect metadata and non-personal identifiers from various sources, including downloads, documentation views, and installations. This data is invaluable in understanding user behavior, engagement, and preferences.
Tracking Documentation Views and Downloads
With Scarf Gateway integrated into your own documentation site, you gain a comprehensive view of user interactions. By tracking documentation views, you can understand which sections of your documentation are most popular and which might require improvement. Additionally, tracking downloads provides insights into the popularity and reach of your software.
User Behavior and Adoption Insights
Scarf Gateway enables you to see how users utilize your software and documentation. Understanding user behavior within your documentation can help you identify pain points and areas where users may struggle. Armed with this knowledge, you can make targeted improvements to enhance the overall user experience.
Identifying User Origins and Represented Companies
One of the most powerful aspects of Scarf Gateway is its ability to identify where your users come from and the companies they represent within your community. This information can be crucial for understanding your project's reach and the impact it has on various industries. By knowing who your users are, you can tailor your documentation and software to better meet their needs.
Optimizing Documentation and Software Strategy
The combination of Scarf and your self-hosted docs site empowers you to make data-driven decisions. Utilize the insights gained to optimize your documentation and software strategy. Tailor your content to target specific user segments, improve areas that require attention, and align your project's goals with the needs of your community.
Fostering Community Engagement
The data collected by Scarf can help you identify active contributors and influential users within your community. Recognizing and engaging with these individuals can foster a stronger sense of community and encourage further collaboration.
Conclusion
In conclusion, using GitHub Repositories as the primary source for your project's documentation can limit its growth and adoption potential. Building your own documentation site allows you to optimize your user experience, integrate your brand's personality, and leverage valuable web knowledge to create a compelling, interactive, and user-friendly documentation hub. As open-source projects continue to thrive on collaboration and community support, investing in high-quality documentation through your self-hosted docs site will undoubtedly prove to be a game-changer for your project's success. So, why settle for less?
Latest blog posts
Tools and strategies modern teams need to help their companies grow.
Keeping your Salesforce accounts in sync with Scarf’s company data gives your team a clearer picture of how organizations are engaging with your open-source project.
Companies offering open source are pouring resources into the project, but it remains a black hole for go-to-market teams—high adoption, but no clear path to conversion. With Scarf, company-level usage data is available while maintaining privacy. The native integration with Salesforce and Hubspot, brings your open source users from passive usage to pipeline acceleration.
Open source projects generate a treasure trove of data (downloads, doc views, project usage), but most open source companies aren’t tapping into it. Here’s how Scarf helps us, and how it can help you do the same with your marketing.
RisingWave, an open-source streaming database, is reshaping real-time data processing with its SQL-powered platform. Before Scarf, RisingWave relied on a Metabase dashboard to track anonymous telemetry. Scarf gave RisingWave the insights they were missing. By providing visibility into company-level engagement, Scarf is helping them identify, track and re-engage with companies already using RisingWave.
Scarf provided Weaviate with the clarity and actionable insights they needed. By integrating Scarf into their open-source project, Weaviate unlocked real-time developer signals, such as download volumes, referral sources, and organizational trends.
Monthly Tracked Companies (MTCs) are the organizations actively engaging with your open source project. This includes downloads of your packages, views of your documentation, and any other type of interaction with your software. Scarf identifies and surfaces these organizations so you can better understand your audience and prioritize outreach.
As 2024 wraps up, we’ve been reflecting on everything that wouldn’t have been possible without the Scarf community and our amazing customers. It’s been a big year for Scarf—and for the open source projects we’re proud to support.
The Scarf Summit brought together open source industry leaders to explore how open source usage signals are shaping the future of commercial open source companies. We were joined by Soham Maniar, Director of RevOps at Weaviate and Kevin White, Head of Marketing at Common Room, to expand on leveraging open source usage data for sales and marketing campaigns.
This playbook will guide you through the steps to set up and embed a Scarf Pixel on your documentation pages, README files, or any other web properties associated with your project, in this case we will focus specifically on documentation.
Today, the most commonly accepted metrics for open source adoption and growth are heavily focused on the contributors and community (the idea is healthy contributions should equate to healthy adoption). While these are useful metrics, they are only part of the picture. This guide is built for those at open-source-based companies who are responsible for growth and adoption.
We’ve got some exciting news: Scarf just launched a powerful, native integration with Salesforce, bringing Scarf’s rich open source usage data directly into your CRM. No more bouncing between tools or setting up S3 data exports—you can now get all the insights you need where you already do your work.
Scarf, a platform designed to provide open-source projects with deeper insights into their users and usage patterns, was the answer ARMO needed. By integrating Scarf into Kubescape, ARMO was able to regain visibility into which company has been using Kubescape, filling the gap left after their CNCF contribution.
The foundation of Scarf company tracking is IP Address attribution. Our Company Tracking algorithm considers confidence and reputation scores from multiple sources to provide what we believe to be the best matching data in the industry. In a nutshell, Match Feedback allows you to fix and fine-tune your company matches.
We're thrilled to announce that Scarf has successfully completed the SOC 2 Type 2 examination! This might sound like legal jargon at first glance, but let’s break down what this means for us, our users, and the open-source community as a whole.
Scarf helps you unlock the full potential of your open source project by collecting valuable usage data in three key ways: Scarf Packages, in-app telemetry, and tracking pixels. In this post, we’ll break down each of these powerful tools and show you how to use them to optimize your open source strategy.
Exporting data tracked by Scarf is essential for analytics, reporting, and integration with other tools. Scarf adds open-source usage metrics to the data you already collect, giving you a fuller picture of how your project is used. This helps you monitor trends, measure impact, and make better data-driven decisions.
In this playbook, you’ll learn how to integrate Scarf into an Apache Software Foundation project. It details how the Preset team implemented Scarf in their Apache Superset project, as shared during our first-ever Scarf Summit on July 16th, 2024.
Prisma turned to Scarf for a monthly Strategic Insights Report. By integrating Scarf into various parts of their web and software delivery infrastructure, Prisma now knows relevant details about their users in terms of company size, industry, location and much more.
Implementing telemetry in your open source project helps you determine whether people are testing your software and continuing its use over time. Such insights not only confirm if the developed software meets users' needs but also helps identify which versions are being adopted and which might be vulnerable to the latest bugs or other issues.
This playbook will walk you through setting up Scarf to get a clearer picture of how people are interacting with your open-source project. You’ll learn how to create and use Scarf Pixels, track open source project documentation views, measure engagement across social media, and more.
CopilotKit implemented Scarf to gain visibility into their open-source community. By adding Scarf to their documentation, they could see which companies were actively engaging with their resources, providing valuable insights into potential leads and customer segments.
Tracking downloads of your open-source projects is key to understanding user engagement. With Scarf, you can see which businesses are using your project, which versions are popular, which platforms are being targeted, and more. This playbook will show you how to set up Scarf to monitor your project’s downloads.
On July 16th, we hosted our first-ever Scarf Summit, celebrating analytics for open source and the significant improvements we’ve made to the Scarf platform. In case you missed it, here’s a recap of all the key updates shared by our Engineering Leader, Aaron Porter.
In this episode of the Haskell Interlude Podcast, Joachim Breitner and Andreas Löh sit down with Avi Press, the founder of Scarf, to discuss his journey with Haskell, the telemetry landscape in open source software, and the technical as well as operational challenges of building a startup with Haskell at its core.
Scarf Basic and Premium tiers have long had the ability to sort their open source usage data by company, domain, events, last seen, and funnel stage. But our customers have been wanting more. Now you can hyper target by combining region, tech stack, and funnel stage, making outreach as refined and low friction as possible.
Understanding open source user engagements and usage is obscured by a lack of actionable data, a result of its inherent openness and anonymity. Embracing a data-driven approach to open source projects helps them not only grow, but also understand the keys to their success, benefiting everyone involved.
As an open source company, Garden knew how hard it was going to be to get usage data. Adding Scarf for analytics on open source downloads turned anonymous numbers into company names. Using Scarf’s privacy-first analytics also helped Garden to know what kind of companies were using their OSS and where they were located.
Once Heroic started using Scarf, they learned that they were even more popular than they thought they were. Using Scarf, they were able to determine where, by country, their users were downloading from, and how many per day.
Any LF project maintainer can use Scarf without needing any further approval from the foundation. Scarf is offering all LF projects free accounts with a few additional features over our base free version. LF projects will get usage data like docs, downloads, and page views with unlimited free seat licenses and data retention.
Union is an open source first company. It uses Scarf to drive their DevRel strategy and improve their open source project. It also uses Scarf to power its consultative sales approach to help customers where it makes sense. Union has been successfully leveraging Scarf funnel analysis to shape the product to better fit the market so that they can focus on ensuring that companies can get value from Flyte sooner.
In this latest episode of "Hacking Open Source Business," Avi Press and Matt Yonkovit sit down with Adam Jacob, the co-founder of Chef and current CEO of System Initiative. With a rich history in the open-source world and numerous thought-provoking opinions, Adam delves into the intricacies of open-source commercialization, offering valuable insights and alternative strategies to the commonly held Open Core model.
Smallstep wanted to understand the impact of their open-source project on enterprise adoption of their commercial security solutions. Smallstep uses Scarf to better understand user interactions and software usage, providing insights into its user base and potential customer segments as an important signal for commercial use.
Diagrid was founded in 2022 by the creators of the popular Dapr open source project. Making data-driven decisions for a commercial company built on an open source project that had no real concrete data, was a real challenge. Diagrid translated Scarf data into valuable insights for marketing and product development of their commercial product.
When we approached the project of building Scarf, we turned to our favorite language: Haskell. Little did we know, this decision would shape our story in more ways than one.
Unstructured had so much usage of their open source, but so little data. Prior to Scarf, they mostly had GitHub information for things like downloads and stars. It was difficult to separate the good signal from the noise without any specific information that would help them to better target this large and growing open source user base or data to influence their product roadmap.
It’s happening! Scarf is part of the Common Room Signal Partners program. Soon, you will be able to integrate your Scarf data into your Common Room platform for a more complete view of all of your user signals.
We are thrilled to announce that we have successfully completed a Type 1 System and Organization Controls 2 (SOC 2) examination for our Scarf Platform service as of January 31, 2024.
When Scarf emerged back in 2019, many people expressed skepticism that usage analytics would ever be tolerated in the open source world. 5 years later, Scarf has shown this once solidified cultural norm can indeed change. Learn how Scarf's journey mirrors a broader shift in open source culture and why embracing usage analytics could shape the future of open software development.
Apache Superset is an open-source modern data exploration and visualization platform that makes it easy for users of all skill sets to explore and visualize their data. We spoke with Maxime Beauchemin, founder & CEO of Preset, and the original creator of both Apache Superset and Apache Airflow, who shared with us Superset's experience using Scarf.
Haskell, a cutting-edge programming language rooted in pure functionality, boasts static typing, type inference, and lazy evaluation. The language's ongoing evolution is bolstered by a diverse array of organizations, including the Haskell.org committee. This committee strategically leveraged the Scarf solution for testing purposes.
We’re pleased to share a final recap of the latest Scarf updates for December and 2023 as a whole. Join us in this last edition of our 2023 newsletters.
In the open source ecosystem, user behaviors are diverse and conversion tracking poses unique challenges frequently leaving traditional marketing strategies insufficient. Recognizing this gap, we are excited to introduce a brand new way for businesses to make sense of this opaque and noisy signal – Open Source Qualified Leads (OQLs).
In recent years, a notable development in the open source landscape is the growing number of large corporations considering the transition from open source licenses to more restrictive models like the Business Source License (BSL). This trend raises further questions about the sustainability and future of open source projects, particularly when large players alter their approach.
A recent release of Scarf added the ability to track and report on custom URL parameters. If you are looking to gain more intelligence around how you open source users interact with your project and download your software using link parameters in key situations can reveal interesting and helpful trends that can help you grow your user base and unlock open source qualified leads.
In the ever-evolving landscape of open source software, data collection has become a hot-button issue. As the open source community grows and software becomes increasingly integral to our daily lives, concerns about data collection ethics have emerged.
In today's fast-paced tech world, the Developer Relations (DevRel) role has moved from the periphery to the center stage. Companies, irrespective of their size, are now seriously considering the worth of having a dedicated DevRel team. But, how do you quantify the success or failure of such an effort? What metrics should companies use? This post dives deep into understanding the commercial Return on Investment (ROI) of DevRel.
Monetizing open source software is a challenging task, but it can also be highly rewarding. Unlike traditional software, you're essentially competing against a free version of your product. So, how do you sell something that is inherently free?
In the dynamic realm of community management, marketing, and developer relations, success depends upon more than just attracting attention. It's about fostering meaningful relationships, nurturing engagement, and amplifying your community's impact.
This guidebook shows you how to implement a call-home functionality or telemetry within your open-source software while at the same time being transparent and respectful of your users data. Let's explore how to build a minimal, privacy-focused call home functionality using a simple version check and Scarf.
Many open source contributors are reluctant or skeptical about metrics. They think metrics are overrated, irrelevant, or even harmful to their projects and communities. But in this blog post, we argue that metrics are essential for making better decisions, improving the experience for users and contributors, and demonstrating the impact and value of your open source work. We also share some tips and examples from OSPOs and DevRel teams on how to choose and use metrics effectively.
Many open-source developers rely on GitHub as their primary documentation source. But this can be a costly mistake that can affect your project’s success and adoption. In this blog, we’ll explain why you need to build your own docs site and how to do it easily and effectively.
Open source projects and companies need data to grow and enhance their performance. However, many open source leaders and communities overlook or reject metrics and depend on intuition, relationships, or imitation. Data can help you spot problems, opportunities, and false positives in growth strategies. In this blog post, Matt Yonkovit shows you why data is important for open source success and how it can offer insights and guidance for open source projects to reach their goals and make better decisions.
Open source software continues to be a vital part of enterprise operations in Q2 2023, as more and more companies adopt open source solutions for their business needs. In this blog post, we will examine the state of open source usage in Q2 2023 and the trends that are shaping the future of open source.
DevRel is a vital function for any organization that wants to engage with the developer community and grow its user base. However, there is no one-size-fits-all solution for where to place DevRel within the organizational structure. In this blog post, we explore three common strategies for DevRel placement: marketing, product, and hybrid. We discuss the advantages and challenges of each strategy, and provide some tips on how to decide which one is best for your organization and goals.
In the open source industry, identifying and engaging users is a major challenge. Many users download software from third-party platforms that do not share user data with the software company. Gating content behind a login or an email form can help, but it can also alienate potential users who value their privacy and convenience. In this blog post, we explore the pros and cons of gating content in the open source industry, and we offer an alternative solution that can help you identify and connect with your users without compromising your content.
Open source software depends on the power of its community. But how do you know if your community is healthy and thriving? In this blog, you will learn how to use metrics to track and evaluate your community’s activity, engagement, growth, diversity, quality, and impact. You will hear from founders, DevRel experts, and investors who share their best practices and tips on how to measure and improve your community’s performance and value.
Learn how to overcome the challenges of open source software marketing and turn anonymous data into qualified leads. In this blog post, we’ll show you how to use download data, web traffic, and documentation views to identify potential customers and grow your sales pipeline. Discover how to track downloads, website traffic and documentation views with Scarf Gateway and the Scarf Tracking Pixel.
This blog post outlines ten common mistakes made by founders of open source startups, from failing to ask the right questions to neglecting the standardization of key metrics. By offering guidance on how to avoid these pitfalls, it provides a roadmap to successfully commercializing open source projects.
Many people believe that making money from open source projects is an arduous or even impossible task. However, with the right strategies it is possible to build a sustainable business while keeping the spirit of open source intact. By evaluating the market fit and commercial viability of an open source project before considering funding and monetization, one can realistically begin to explore the financial potential of an open source project. Here's how to do it.
This blog emphasizes the importance of a comprehensive approach to lead generation in the open source software space. Amid the challenges of anonymous usage and privacy regulations, strategies focusing on download activity, community engagement, and web traffic can maximize lead identification. Employing lead scoring and maintaining a list of active software users can further enhance sales outcomes in this unique market.
Here at Scarf, we've developed a solution to help open source projects and businesses gain more insight into their users and their download traffic - Scarf Gateway. Here's how it works.
We are thrilled to announce our latest partnership with Clearbit (https://clearbit.com/). This collaboration will offer Scarf users and customers an enriched array of data about their user base, significantly enhancing the quality of information you already value from Scarf.
The popularity of open source software is not in doubt, but little concrete public data exists beyond human-generated surveys on adoption usage. In this blog post, we will explore the state of open source usage in Q1 2023 and the data illustrating how open source is becoming an increasingly important part of enterprise operations.
The success of DevRel (Developer Relations) and community efforts in open source can be challenging to measure, as there is often a disconnect between the goals and expectations of the community and the business. This blog post discusses the challenges of measuring the success of DevRel and community efforts in open source.
Successful open source projects don't always translate into successful open source businesses. However, by focusing on building a kick-ass product, raising awareness, making the product easier to use, and fostering a strong open source community, you can set the stage for converting users into paying customers.
You can use the open source Scarf Gateway to switch hosting providers, container registries, or repositories without impacting end users in the future.
What is driving all this tech layoffs? , What is their impact on the open source software industry? We will walk through all the potential reasons from an economic downturn, herd mentality, excessive borrowing and spending due to low interest rates, and growth at all costs as the main reasons behind the layoffs. Companies can continue to grow in this tight economic market if they are focused on optimizing efficiency and sustaining the right growth.
At the All Things Open conference, Emily Omier, a seasoned positioning consultant, sat down with Avi Press (Founder and CEO, Scarf) and Matt Yonkovit (The HOSS, Scarf) to discuss how to message, position, and validate your open source product on The Hacking Open Source Business Podcast. You can watch the full episode below or continue reading for a recap.
On the Hacking Open Source Business podcast, Joseph Jacks aka JJ (Founder, OSS Capital) joins Avi Press (Founder and CEO, Scarf) and Matt Yonkovit (The HOSS, Scarf) to share what you need to know before starting a commercial open source software (COSS) company and how you can set yourself and your project apart in a way that attracts investor funding. As an investor who exclusively focuses on open source startups, JJ provides a VC perspective on what he looks for when evaluating investment opportunities.
On The Hacking Open Source Business podcast, CEO Chris Molozian and Head of Developer Relations Gabriel Pene at Heroic Labs elaborate on their usage and shift to open source and how it accelerated their adoption.
In this recap of the first episode of the Hacking Open Source Business Podcast, co-hosts Matt Yonkovit and Avi Press, Scarf Founder and CEO, dig into a recent controversy that highlights the challenges open source projects face trying to create sustainable revenue streams to support a business or a non-profit that funds the project’s growth.
Scarf Sessions is a new stream where we have conversations with people shaping the landscape in open source and open source sustainability. This post will give a recap of the conversation Scarf CEO, Avi Press and I had with our guest Stefano Maffulli.
Community is important to the success of open source software. To understand and grow a community, project founders and maintainers need visibility into various technical, social, and even financial metrics. But what metrics should we be using?
Should Python eggs be deprecated in favor of wheels? What does the data show? This post explores how the right data can make decisions like this easier for maintainers and Open Source organizations.
Keeping your Salesforce accounts in sync with Scarf’s company data gives your team a clearer picture of how organizations are engaging with your open-source project.
Companies offering open source are pouring resources into the project, but it remains a black hole for go-to-market teams—high adoption, but no clear path to conversion. With Scarf, company-level usage data is available while maintaining privacy. The native integration with Salesforce and Hubspot, brings your open source users from passive usage to pipeline acceleration.
Open source projects generate a treasure trove of data (downloads, doc views, project usage), but most open source companies aren’t tapping into it. Here’s how Scarf helps us, and how it can help you do the same with your marketing.
Why GitHub Repos Are Not Enough for Your Docs: The Benefits of Creating a Dedicated Doc Site
Facebook
Twitter
linkedin
Email
Introduction
Documentation is the backbone of any successful open-source project. It not only serves as a guide for developers and users but also acts as a vital marketing tool for attracting new users. However, many developers make the common mistake of using their GitHub repository as the primary source for documentation. In this blog, we will explore the limitations of using GitHub as your primary documentation source and the benefits of using your own docs site for hosting your project's documentation.
Using your GitHub Repo as your Primary Documentation Source: Limitations
You may think that using your GitHub repo for your documentation is a quick and easy solution, but you may be missing out on a lot of benefits that building your own docs site can offer. Your GitHub repo has several drawbacks that can affect your documentation quality and user satisfaction. Here are some of them:
It has poor formatting and styling options. It only supports Markdown, which is a simple markup language that can create basic text formatting. However, it cannot create more advanced and attractive content, such as interactive elements, custom fonts, colors, or layouts.
It has limited media and asset support. It only allows you to embed images and links in your documentation. You cannot include other types of media, such as videos, tutorials, or code examples, that can make your documentation more engaging and helpful for your users.
Using GitHub for docs is easy but suboptimal. Building your own docs site can provide your users of better quality documentation and an optimized user experience.
Documentation as Your #1 Marketing Tool
When you create an open-source project, you want to share it with the world and get more people to use it and contribute to it. But how do you convince them that your project is worth their time and attention? How do you make a good first impression and build trust and loyalty with your users? The answer is documentation.
Documentation is more than just a technical guide; it is also a powerful marketing tool for your open-source project. It is the first thing that potential users will see when they visit your project’s website or repository. It is the way you communicate your project’s vision, purpose, features, and benefits to your audience. It is the way you show your project’s personality and brand identity, and how you integrate it with your main website.
By building your own docs site for your project’s documentation, you can create a user-friendly and branded experience that showcases your project in the best possible light. You can customize the look and feel of your documentation to match your project’s style and tone. You can use images, logos, colors, fonts, and layouts that reflect your project’s identity and values. You can also link your documentation to your main website, social media accounts, or other relevant platforms, creating a seamless and consistent user journey.
Embracing Interactivity and Rich Media
One of the advantages of using your own docs site for your documentation is that you can add interactivity and rich media to your content, which can enhance the user experience and learning outcomes. Interactivity and rich media can help you:
Capture the user’s attention and interest with engaging visuals and sounds.
Explain complex concepts and processes with clear and concise demonstrations and examples.
Provide feedback and guidance to the user with interactive tools and exercises.
Encourage the user to explore and experiment with your project’s features and functionalities.
By building your own docs site, you can embed various types of interactivity and rich media into your documentation, such as videos, conference talks, tutorials, and code examples directly into your documentation, making it a more engaging and valuable resource for your audience.
Interactivity and rich media can enhance your open source project documentation by engaging the user, demonstrating concepts, guiding the user, and stimulating exploration.
Utilizing Two Decades of Web Knowledge
The web has evolved tremendously over the last two decades, and so has our understanding of how to create effective and user-friendly websites. By using your own docs site for your documentation, you can leverage this web knowledge and apply it to your documentation website, creating a better experience for your users and yourself. Here are some of the benefits of using your own docs site in terms of web knowledge:
Optimized navigation: Building your documentation site allows you to create a clear and intuitive navigation system for your documentation, making it easy for your users to find what they are looking for. You can use menus, tabs, breadcrumbs, or other navigation elements to organize your documentation into logical sections and sub-sections. You can also use internal links to connect related pages or topics within your documentation, creating a coherent and consistent flow of information.
Enhanced searchability: Building a site for your documentation enables you to improve the searchability of your documentation, both internally and externally. Internally, you can use a search box or a search engine plugin to allow your users to search for keywords or phrases within your documentation, saving them time and effort. Externally, you can use SEO (Search Engine Optimization) techniques to increase the visibility and ranking of your documentation website on popular search engines like Google or Bing, attracting more traffic and potential users to your project.
Detailed analysis: Having your own docs site provides you with access to various analysis tools that can help you understand your users’ behavior and needs better. Some of these tools are: ◦ Scarf: A privacy-preserving analytics platform that tracks how your documentation website is used and by whom. You can use Scarf to measure the number of visitors, page views, bounce rate, average time spent, most popular pages, etc. You can also use Scarf to identify the organizations and companies that are using your documentation website, and how they are using it. ◦ Google Analytics: A widely used web analytics service that tracks and reports website traffic. You can use Google Analytics to measure the performance of your documentation website, such as the user acquisition, behavior, and conversion rates. You can also use Google Analytics to segment your users by various criteria, such as location, device, browser, etc. ◦ Matomo: A free and open source web analytics platform. Matomo is a great alternative to Google Analytics if you want to have full control over your own data and avoid sharing it with third parties. You can also use Matomo to create custom reports and dashboards that suit your needs. ◦ Mixpanel: A user analytics platform that helps you understand how your users interact with your documentation website. You can use Mixpanel to track the actions and events that your users perform on your documentation website, such as clicking a button, downloading a file, or completing a form. You can also use Mixpanel to create funnels, cohorts, and retention reports that show how your users progress and engage with your documentation website.
By using these analytics tools, you can gain a comprehensive and holistic understanding of your users’ behavior and needs. You can also use feedback forms, surveys, or comments to collect direct feedback from your users, learning about their satisfaction, preferences, or suggestions for improvement.
By building a site for your documentation, you can utilize two decades of web knowledge and best practices to create a more effective and user-friendly documentation website.
Catering to Different User Preferences
One of the main goals of any open-source project is to get more users and contributors to join and support your project. However, this can be challenging if your documentation is not appealing or accessible to a wide range of users. Different users may have different preferences, needs, or expectations when it comes to documentation. How do you create documentation that satisfies and attracts all kinds of users?
The solution is building your own docs site. This allows you to create an interactive static-generated site that can cater to different user preferences and increase the adoption of your open-source project.
The Solution
The best way to create your own docs site is to use a static site generator (SSG) such as Hugo, Docusaurus, Doscify, and so on. These tools allow you to build your docs site from your own repository and host it on a platform like Github Pages, Read the Docs, or any other service of your choice.
There are many alternatives for storing your documentation off GitHub, depending on your budget, skills, and requirements. Here are some of the most popular ones:
Read the Docs: Read the Docs is a free and open source platform that hosts documentation for thousands of open source projects. It supports various formats like Markdown, reStructuredText, AsciiDoc, and Sphinx, and integrates with GitHub, GitLab, Bitbucket, and other version control systems. It also provides features like versioning, translations, search, PDF export, custom domains, and analytics.
GitBook: GitBook is a paid platform that lets you create beautiful and interactive documentation from Markdown files. It integrates with GitHub and other version control systems, and provides features like collaboration, comments, search, custom domains, analytics, and more.
Docusaurus: Docusaurus is a free and open source static site generator that helps you create documentation websites from Markdown files. It integrates with GitHub and other version control systems, and provides features like versioning, translations, search, custom themes, plugins, and more.
MkDocs: MkDocs is another free and open source static site generator that helps you create documentation websites from Markdown files. It integrates with GitHub and other version control systems, and provides features like themes, plugins, search, navigation, custom domains, and more.
Read the Docs is a free platform that hosts documentation for open source projects, supports various formats and integrations, and offers features like versioning, translations, and analytics.
Building your own documentation site is the perfect solution to convert your static documentation into an interactive, dynamic, and user-friendly website. With your own docs site, you can maintain the simplicity of Markdown while adding powerful features like embedded coding tools, examples, and training modules.
Combining Scarf Analytics with Your Documentation Site
You have seen how building your own documentation site can help you create and host your project’s documentation with ease and efficiency. But what if you want to know more about who is using your documentation and software, and how they are using it? That’s where Scarf comes in. Scarf is a powerful platform that tracks and analyzes how your documentation website and software are used and by whom. It can provide you with valuable data and insights that can help you improve your project and reach more users. In this section, we will show you how to integrate Scarf Gateway with your docs site and how this combination can take your open-source project to the next level.
Understanding Scarf Analytics
Scarf Gateway acts as a bridge between your users and the current distribution channels of your software. The installation and deployment methods remain unchanged, ensuring a seamless user experience. What sets Scarf apart is its ability to collect metadata and non-personal identifiers from various sources, including downloads, documentation views, and installations. This data is invaluable in understanding user behavior, engagement, and preferences.
Tracking Documentation Views and Downloads
With Scarf Gateway integrated into your own documentation site, you gain a comprehensive view of user interactions. By tracking documentation views, you can understand which sections of your documentation are most popular and which might require improvement. Additionally, tracking downloads provides insights into the popularity and reach of your software.
User Behavior and Adoption Insights
Scarf Gateway enables you to see how users utilize your software and documentation. Understanding user behavior within your documentation can help you identify pain points and areas where users may struggle. Armed with this knowledge, you can make targeted improvements to enhance the overall user experience.
Identifying User Origins and Represented Companies
One of the most powerful aspects of Scarf Gateway is its ability to identify where your users come from and the companies they represent within your community. This information can be crucial for understanding your project's reach and the impact it has on various industries. By knowing who your users are, you can tailor your documentation and software to better meet their needs.
Optimizing Documentation and Software Strategy
The combination of Scarf and your self-hosted docs site empowers you to make data-driven decisions. Utilize the insights gained to optimize your documentation and software strategy. Tailor your content to target specific user segments, improve areas that require attention, and align your project's goals with the needs of your community.
Fostering Community Engagement
The data collected by Scarf can help you identify active contributors and influential users within your community. Recognizing and engaging with these individuals can foster a stronger sense of community and encourage further collaboration.
Conclusion
In conclusion, using GitHub Repositories as the primary source for your project's documentation can limit its growth and adoption potential. Building your own documentation site allows you to optimize your user experience, integrate your brand's personality, and leverage valuable web knowledge to create a compelling, interactive, and user-friendly documentation hub. As open-source projects continue to thrive on collaboration and community support, investing in high-quality documentation through your self-hosted docs site will undoubtedly prove to be a game-changer for your project's success. So, why settle for less?
By clicking “Accept all”, you agree to the storing of cookies on your device to enhance site navigation, analyze site usage, and assist in our marketing efforts. View our Cookie Policy for more information.
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.avif)
.svg)
.svg)
.svg)
.svg)
