Scarf Announces Integration with Common Room

Why GitHub Repos Are Not Enough for Your Docs: The Benefits of Creating a Dedicated Doc Site

Published

July 26, 2023

This article was originally posted on

Hackernoon

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.
a checklist for a team
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.

Digital creative of a browser on the internet
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.
Managed Read the Docs hosting in EU Cloud - Stellar Hosted
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.

How Garden Leverages Scarf to Understand and Grow Their User Base

How Garden Leverages Scarf to Understand and Grow Their User Base

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.
OSS Privacy & OSS Analytics, How Heroic Labs Struck a Balance

OSS Privacy & OSS Analytics, How Heroic Labs Struck a Balance

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.
Unlimited Free Seats and Data Retention for All Linux Foundation Projects

Unlimited Free Seats and Data Retention for All Linux Foundation Projects

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.ai and Flyte: Privacy, Open Source, and Building a Commercial Business

Union.ai and Flyte: Privacy, Open Source, and Building a Commercial Business

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.
Navigating the Complexities of Open Source Commercialization: Insights from Adam Jacob

Navigating the Complexities of Open Source Commercialization: Insights from Adam Jacob

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.
Scarf Newsletter - May 2024

Scarf Newsletter - May 2024

Stay up to date with the latest updates from Scarf. Discover upcoming features, industry news, partnerships, and events. May 2024 Newsletter.
Smallstep Labs: Leveraging Open Source Data for Enterprise Growth

Smallstep Labs: Leveraging Open Source Data for Enterprise Growth

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 and Dapr: How to Balance Open Source and Business Through Data

Diagrid and Dapr: How to Balance Open Source and Business Through Data

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.
12 Reasons Why Haskell is a Terrible Choice for Startups  (and why we picked it anyway)

12 Reasons Why Haskell is a Terrible Choice for Startups (and why we picked it anyway)

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: Understanding an Open Source Project’s Impact on Commercial Success

Unstructured: Understanding an Open Source Project’s Impact on Commercial Success

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. 
New Integration: Scarf + Common Room = Supercharged Insights for Open Source Projects

New Integration: Scarf + Common Room = Supercharged Insights for Open Source Projects

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.
Scarf Newsletter - March 2024

Scarf Newsletter - March 2024

Stay up to date with the latest updates from Scarf. Discover upcoming features, industry news, partnerships, and events. March 2024 Newsletter.
State of Open Source Usage: The Scarf Report 2023

State of Open Source Usage: The Scarf Report 2023

In 2023, the open source software (OSS) landscape showed significant growth and shifts in various aspects. Here are the key findings:
Scarf Successfully Completes Type 1 SOC 2 Examination with an Unqualified Opinion

Scarf Successfully Completes Type 1 SOC 2 Examination with an Unqualified Opinion

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.
Analytics are Starting to Win in Open Source

Analytics are Starting to Win in Open Source

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.
Scarf Newsletter - February 2024

Scarf Newsletter - February 2024

Stay up to date with the latest updates from Scarf. Discover upcoming features, industry news, partnerships, and events. February 2024 Newsletter.
Scarf Case Study: Apache Superset

Scarf Case Study: Apache Superset

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.org: Bridging the Gap Between Language Innovation and Community Understanding

Haskell.org: Bridging the Gap Between Language Innovation and Community Understanding

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.
Scarf Newsletter - December 2023

Scarf Newsletter - December 2023

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.
Introducing OQLs: A New Way for Businesses to Quantify Open Source Adoption

Introducing OQLs: A New Way for Businesses to Quantify Open Source Adoption

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).
Scarf Newsletter - November 2023

Scarf Newsletter - November 2023

Stay up to date with the latest updates from Scarf. Discover upcoming features, industry news, partnerships, and events. November 2023 Newsletter.
The BSL Phenomenon: Balancing Sustainability and Open Source Principles

The BSL Phenomenon: Balancing Sustainability and Open Source Principles

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.
State of Open Source Usage Q3 2023: The Scarf Report

State of Open Source Usage Q3 2023: The Scarf Report

In Q3 2023, the open source software (OSS) landscape showed significant growth and shifts in various aspects. Here are the key findings:
Unlocking the Power of Custom URL Parameters with Scarf: A Comprehensive Guide

Unlocking the Power of Custom URL Parameters with Scarf: A Comprehensive Guide

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.
Building Trust: How to Collect Data Responsibly as an Open Source Project

Building Trust: How to Collect Data Responsibly as an Open Source Project

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.
Scarf Newsletter - September 2023

Scarf Newsletter - September 2023

Stay up to date with the latest updates from Scarf. Discover upcoming features, industry news, partnerships, and events. September 2023 Newsletter.
 Measuring the Commercial ROI of DEVREL

Measuring the Commercial ROI of DEVREL

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.
Selling Open Source: 101 - Guide for Sales and Marketing Teams

Selling Open Source: 101 - Guide for Sales and Marketing Teams

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?
Beyond the Surface: How to Engage with the Quiet Members of your Open Source Community

Beyond the Surface: How to Engage with the Quiet Members of your Open Source Community

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. 
Mastering Telemetry in Open Source: A Simple Guide to Building Lightweight Call Home Functionality

Mastering Telemetry in Open Source: A Simple Guide to Building Lightweight Call Home Functionality

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.
Scarf Newsletter - July 2023

Scarf Newsletter - July 2023

Stay up to date with the latest updates from Scarf. Discover upcoming features, industry news, partnerships, and events. July 2023 Newsletter.
Open Source Metrics: Fear and Loathing (Part 2)

Open Source Metrics: Fear and Loathing (Part 2)

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.
Why GitHub Repos Are Not Enough for Your Docs: The Benefits of Creating a Dedicated Doc Site

Why GitHub Repos Are Not Enough for Your Docs: The Benefits of Creating a Dedicated Doc Site

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.
Data-Driven Open Source: Why You Should Care About Metrics (Part 1)

Data-Driven Open Source: Why You Should Care About Metrics (Part 1)

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.
State of Open Source Usage Q2 2023: The Scarf Report

State of Open Source Usage Q2 2023: The Scarf Report

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.
Developer Relations (DevRel): Where Should It Reside in Your Organization

Developer Relations (DevRel): Where Should It Reside in Your Organization

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.
The Gating Debate: Striking a Balance Between Open Source and Marketing Insights

The Gating Debate: Striking a Balance Between Open Source and Marketing Insights

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.
How to Use Metrics to Track and Evaluate Your Open Source Community’s Success

How to Use Metrics to Track and Evaluate Your Open Source Community’s Success

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.
How to: Using anonymous downloads, website traffic, and documentation views to generate leads

How to: Using anonymous downloads, website traffic, and documentation views to generate leads

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.
Why Your Open Source Startup Is Going To Fail (And What You Can Do About It)

Why Your Open Source Startup Is Going To Fail (And What You Can Do About It)

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.
Open Source Monetization 101: A Step-by-Step Guide

Open Source Monetization 101: A Step-by-Step Guide

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.
The Open Source Sales & Marketing Funnel: Navigating the Challenges of Anonymous Downloads and Activity Tracking

The Open Source Sales & Marketing Funnel: Navigating the Challenges of Anonymous Downloads and Activity Tracking

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.
Scarf Newsletter - May 2023

Scarf Newsletter - May 2023

Stay up to date with the latest updates from Scarf. Discover upcoming features, industry news, partnerships, and events. May 2023 Newsletter.
Harnessing Software Download Patterns: Using Open Source Download Metrics to Uncover New Users and Potential Customers

Harnessing Software Download Patterns: Using Open Source Download Metrics to Uncover New Users and Potential Customers

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.
Unlocking Growth Potential: Scarf Users Benefit from Clearbit Integration for Improved User Intelligence

Unlocking Growth Potential: Scarf Users Benefit from Clearbit Integration for Improved User Intelligence

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.
State of Open Source Usage Q1 2023: The Scarf Report

State of Open Source Usage Q1 2023: The Scarf Report

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.
Connecting Community Efforts in Open Source to Business Success

Connecting Community Efforts in Open Source to Business Success

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.
3 Keys to Growing the Adoption of an Open Source Project

3 Keys to Growing the Adoption of an Open Source Project

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.
The Most Neglected and Overlooked Open Source Metric: Production Users

The Most Neglected and Overlooked Open Source Metric: Production Users

Everyone wants a larger open source user base, but very few people effectively measure its growth. Let’s discuss why.
Switching Container Registries With Zero Downtime

Switching Container Registries With Zero Downtime

You can use the open source Scarf Gateway to switch hosting providers, container registries, or repositories without impacting end users in the future.
Understanding Tech Layoffs and the Economy’s Impact on Open Source

Understanding Tech Layoffs and the Economy’s Impact on Open Source

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.
Why Downloads are an Essential Metric for Open Source Software Projects

Why Downloads are an Essential Metric for Open Source Software Projects

If you're only going to track one thing for your OSS project, track your downloads.
The Open Source Business Metrics Guide

The Open Source Business Metrics Guide

How to Build, Grow, and Measure the Success of an Open Source Business
Messaging and Positioning Considerations for Introducing an Open Source Product

Messaging and Positioning Considerations for Introducing an Open Source Product

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.
How to Get the Attention of an Open Source Software Investor

How to Get the Attention of an Open Source Software Investor

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.
Heroic Labs' Journey to Open Source and 5.3M Docker Downloads

Heroic Labs' Journey to Open Source and 5.3M Docker Downloads

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.
How to Keep Open Source Projects Open Source

How to Keep Open Source Projects Open Source

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.
How Buoyant Drives Open-Source-Led Growth with Linkerd

How Buoyant Drives Open-Source-Led Growth with Linkerd

Building a business around an open-source project is hard. Learn more about how Buoyant drives product-led growth with Linkerd.
Alex Biehl: Open Sourcing a Tool to Generate Haskell Server Stubs

Alex Biehl: Open Sourcing a Tool to Generate Haskell Server Stubs

Alex is a software engineer at Scarf who recently open sourced a tool to generate Haskell server stubs called Tie.
Tanner Linsley: Building Sustainable Open Source Projects

Tanner Linsley: Building Sustainable Open Source Projects

Tanner Linsley joined us to explain how he got started in open source and how he has made working in open source sustainable.
Stefano Maffulli: An Exploration on Standards for Open Source Packaging and Distribution

Stefano Maffulli: An Exploration on Standards for Open Source Packaging and Distribution

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.
Using OSS Usage Data to Sell your Company

Using OSS Usage Data to Sell your Company

Learn how Nestybox used Scarf to gather better project insights and provide accurate data during their recent acquisition.
A Different Approach to Measuring Open Source Community Health

A Different Approach to Measuring Open Source Community Health

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?
Scarf Tech Stack: Relude

Scarf Tech Stack: Relude

This blog post will talk about Relude, a project we use in the majority of our Scarf tech stack
Python Wheels vs Eggs (And How Data-Driven Decisions Must Become The Norm in Open-Source)

Python Wheels vs Eggs (And How Data-Driven Decisions Must Become The Norm in Open-Source)

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.
Changelog: Company Identification Change

Changelog: Company Identification Change

Announcing a new change to the way we identify companies.
Announcing Python Support

Announcing Python Support

Advanced registry analytics are now available for Python package maintainers
Project Spotlight: Scarf Gateway Stats

Project Spotlight: Scarf Gateway Stats

This Project Spotlight will focus on another exciting open source project, Scarf Gateway Stats.
Scarf Will Block Package Downloads from the Russian Government

Scarf Will Block Package Downloads from the Russian Government

In solidarity with Ukraine, Scarf Gateway will no longer service package downloads from Russian Government sources.
Changelog: New Pixel Snippet

Changelog: New Pixel Snippet

A notice to our Documentation Insights users.
Community Spotlight: nix-community

Community Spotlight: nix-community

This is the second post in a new series from Scarf: Spotlights where we highlight awesome projects and communities.
Changelog: Registry Validation for Auto-package Creation

Changelog: Registry Validation for Auto-package Creation

A summary of the new registry validation feature for auto-package creation.
Three Ways to Build Better Products Through Analytics

Three Ways to Build Better Products Through Analytics

A special guest post from open-source analytics company PostHog
New Year, New Scarf Features

New Year, New Scarf Features

Today, we're launching some of the most frequently asked for features since we launched Scarf Gateway back in March.
The Scarf Tech Stack

The Scarf Tech Stack

How Scarf is built
OSS Project Spotlight: IHP

OSS Project Spotlight: IHP

In a new blog post series, we'll highlight great OSS projects that are using Scarf. Today, we are featuring IHP, a modern batteries-included Haskell web framework
Measuring Downloads of Anything You Distribute

Measuring Downloads of Anything You Distribute

Scarf's core registry infrastructure has leveled up to support any kind of direct file download
Announcing Nomia and the Scarf Environment Manager

Announcing Nomia and the Scarf Environment Manager

Our mission here at Scarf centers around enhancing the connections between open source software maintainers and end users. Learn how Scarf + Nomia can reduce the complexity and increase the efficiency of the end-user open source integration experience.
Announcing The Scarf Gateway

Announcing The Scarf Gateway

Understand how your containers are downloaded and decouple your project from your registry
Composition with Semantically Rich Names

Composition with Semantically Rich Names

Insights from recent developments in name-based composition
Shea Levy, Composition Fanatic

Shea Levy, Composition Fanatic

Introducing Shea, Scarf's new VP of Engineering
Are Package Registries Holding Open-Source Hostage?

Are Package Registries Holding Open-Source Hostage?

Package registries are a central piece of infrastructure for software development. How aligned are they with the developers who make all of the packages being hosted?
Analytics and Open Source Sustainability

Analytics and Open Source Sustainability

Analytics will be an important part of improving sustainability for open-source maintainers
OSS Privacy & OSS Analytics, How Heroic Labs Struck a Balance
June 11, 2024

OSS Privacy & OSS Analytics, How Heroic Labs Struck a Balance

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.
Scarf
Scarf
Unlimited Free Seats and Data Retention for All Linux Foundation Projects
June 10, 2024

Unlimited Free Seats and Data Retention for All Linux Foundation Projects

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.
Scarf
Scarf
Playbook

Why GitHub Repos Are Not Enough for Your Docs: The Benefits of Creating a Dedicated Doc Site

General
Analytics for open source
Try for Free
Try for Free

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.
a checklist for a team
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.

Digital creative of a browser on the internet
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.
Managed Read the Docs hosting in EU Cloud - Stellar Hosted
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?