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.

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.

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.

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?