feat: Add maintainers guide section (open-sauced#205)

* Add maintainers guide section

* Add contrib list pic

* Add lists section of guide

* Add understanding lists data, first draft

* Revise Understanding lists Data for clarity and brevity

* Remove spaces

* Add highlights section

* Move gifs to gif folder and update in guide

* Add new pages to sidebar

* Fix name

* Update item names

* Use the same title as sidebar label

* Link to guide from insights page

* Add links to maintainers guide in lists page

* Update lists to include sync your GitHub Team

* Fix spacing and indentation
* Fix punctuations for titles

* Fix capitalizations and punctuations

* Fix typo and adjust wordings in maintainers-guide.md

* Fix typo and adjust wordings in understanding-insights.md

* Fix typo and adjust wordings in understanding-lists-data.md

* Fix broken internal links

* Use same title as sidebar label for Understanding Lists Data

* Bold the ways to add a list and minor fix

* Change link to FAQ with internal link

* Add link to extension

Co-authored-by: Ayu Adiati <45172775+adiati98@users.noreply.github.com>

* Clarify default state of lists

Co-authored-by: Ayu Adiati <45172775+adiati98@users.noreply.github.com>

* add missing word

Co-authored-by: Ayu Adiati <45172775+adiati98@users.noreply.github.com>

* Clarify Highlights tab

* remove incorrect description of list dashboard

* Simplify sentence

* Clarify languages

* Remove chrome ext reference

* Update docs/maintainers/maintainers-guide.md

Co-authored-by: Ayu Adiati <45172775+adiati98@users.noreply.github.com>

* Change word churn to alumni

* Change capital letters to lowercase

* Change h4 to h3

* Change capital letters to lowercase

---------

Co-authored-by: Ayu Adiati <retno.ayu98@gmail.com>
Co-authored-by: Ayu Adiati <45172775+adiati98@users.noreply.github.com>

docs/features/insights.md

@@ -1,21 +1,27 @@
 ---
 id: insights
-title: 'Insights into open source projects'
-sidebar_label: 'Insights'
+title: 'Insights into Open Source Projects'
+sidebar_label: Insights
 keywords:
-- insights
+  - insights
 ---
-The Insights feature is your one-stop solution for understanding the pulse of your open-source projects and contributions. This feature is designed to provide a comprehensive view of your project's health and your individual contributions. From contribution trends to community health, OpenSauced Insights helps you make data-driven decisions that align with your goals. It's not just about numbers; it's about providing data to help you make decisions that can define your approach to open source and tell the story of your project or contribution journey.
+
+The Insights feature is your one-stop solution for understanding the pulse of your open source projects and contributions. This feature is designed to provide a comprehensive view of your project's health and your individual contributions. From contribution trends to community health, OpenSauced Insights helps you make data-driven decisions that align with your goals. It's not just about numbers; it's about providing data to help you make decisions that can define your approach to open source and tell the story of your project or contribution journey.
 
 ![insight-pages-demo](../../static/gif/insight-page-demo.gif)
 
-## How to use Insights
+## How to Use Insights
+
 ### Contributors
+
 - Track your contributions and the impact you're making.
 - Find new projects to contribute to.
 - Discover other contributors to collaborate with.
 
 ### Maintainers
+
 - Track the health of your project.
 - Identify contributors who are making an impact.
 - Find new contributors to support your project.
+
+To learn more about how to use Insights, check out our [Maintainers Guide](../maintainers/maintainers-guide.md) and our [Understanding Insights Data page](../maintainers/understanding-insights.md).

docs/features/lists.md

@@ -1,24 +1,28 @@
 ---
 id: lists
 title: 'Organize and Monitor Your Contributors'
-sidebar_label: 'Lists'
+sidebar_label: Lists
 keywords:
-- lists
+  - lists
 ---
+
 The Lists feature enables you to categorize, monitor, and analyze different groups of contributors within open source projects. With the Lists feature, gain granular insights into each contributor's activity and contributions.
 
-Monitor individual commit histories, track who is actively engaged, identify churned or new contributors, and even compare the performance of contributors against each other. This encompasses a wide range of metrics such as code commits, created and reviewed Pull Requests (PRs), as well as issue creation and commenting. 
+Monitor individual commit histories, track who is actively engaged, identify alumni or new contributors, and even compare the performance of contributors against each other. This encompasses a wide range of metrics such as code commits, created and reviewed Pull Requests (PRs), as well as issue creation and commenting.
 
 ![lists-page](../../static/img/lists-page.svg)
 
 ## How to Create a List
-After logging in, navigate to your [Lists page](https://app.opensauced.pizza/hub/lists/). 
 
-There are two ways to add a list:
-1. Explore Contributors: Use our explore tool to find contributors and create your list.
-2. Import your GitHub following:
-Connect to your GitHub to create a list with all the Contributors you follow.
+After logging in, navigate to your [Lists Page](https://app.opensauced.pizza/hub/lists/).
+
+There are three ways to add a list:
+
+1. **Explore Contributors**: Use our explore tool to find contributors and create your list.
+2. **Sync your GitHub Team**: Connect to your GitHub to create a list from a team in your organization.
+3. **Import your GitHub Following**:
+   Connect to your GitHub to create a list with all the Contributors you follow.
 
 Once your list is created, you'll be able to see an overview of all the contributors in your list, a graph of their activity, and a detailed breakdown of the contributors.
 
-If you're having trouble syncing your Organization or Team, check out our [Sync Your GitHub Team in our FAQs](https://docs.opensauced.pizza/community/faqs/#sync-your-github-team).
+If you're having trouble syncing your Organization or Team, check out our [Sync Your GitHub Team in our FAQs](../community/faqs.md#sync-your-github-team).

docs/maintainers/maintainers-guide.md

@@ -0,0 +1,178 @@
+---
+id: maintainers-guide-to-open-sauced
+title: 'Maintainers Guide to OpenSauced'
+sidebar_label: Maintainers Guide to OpenSauced
+keywords:
+  - maintainers
+  - guides
+---
+
+## Introduction to OpenSauced for Maintainers
+
+OpenSauced is a platform dedicated to empowering maintainers and redefining open source contributions. We offer a GitHub-powered dashboard for tracking contributions and gaining insights into your open source projects. You can customize your Insights Pages and Lists with the repositories you choose and the contributors you want to see.
+
+## Getting Started
+
+To get started, you will need to create an account on OpenSauced. You can do this by visiting the [app.opensauced.pizza](https://app.opensauced.pizza) and clicking the "Connect with GitHub" button. You will be prompted to sign in with your GitHub account. Once you have signed in, you will be redirected to the OpenSauced dashboard.
+
+## Insights: Connecting Your Repositories
+
+OpenSauced Insights provides maintainers with a visual representation of their project's health and contributor engagement. It offers real-time data and analytics to understand contribution patterns, identify key contributors, and measure the project's growth. Insights can help you assess team activity, understand when bottlenecks occur, identify where resource allocation is needed, plan and identify key contributors, understand alumni contributors, or spot emerging trends.
+
+Insights features allow you to:
+
+- track the contributions of a specific team, a specific repository, or a group of repositories,
+- view the number of pull requests that are open, closed, in draft, and merged,
+- view the average number of days it takes for a pull request to be merged (PR velocity),
+- identify the top contributors to your project,
+- identify the current activity level and trends in activity of your contributors.
+
+### Creating a New Insight Page
+
+To connect your repositories, click the "Insights" tab on the dashboard. You will be redirected to a page where you can create your new Insight Page.
+
+There are two ways to add repositories to your Insight Page:
+
+1. **Sync GitHub organization**. Syncing your GitHub organization is a good idea for someone who seeks a comprehensive, unified view of your organization's open source project activities and trends, enabling streamlined management, strategic decision-making, and efficient allocation of resources across multiple repositories.
+2. **Connect individual repositories**. Connecting individual repositories is a good idea for someone who wants to track the contributions of a specific repository or group of repositories. For example, you might want to track projects you maintain that are not under the same organization, or you may want to track projects that align with your team's objectives.
+
+![sync team gif](../../static/gif/team-sync-insights.gif)
+
+### Using Your Insights Page
+
+Once you have connected your repositories, you will be redirected to your Insight Page. Here, you will see a dashboard with an overview of the repositories and the contributors who have contributed to them.
+
+There are three tabs that provide you with more information on these repositories:
+
+#### Reports
+
+The Reports tab allows paid users to filter for more information about their repositories over the last 30 days and to generate a Downloadable CSV. Filters include: Top 100 Repos, Minimum 5 Contributors, Recent, Most Active, and Spammed.
+
+#### Repositories
+
+The Repositories tab allows you to view more detailed information on each repository, including Activity, PR Overview, PR Velocity, Spam, Contributors, and activity over the last 30 days. To learn more about these features, see [Understanding Insights Data](understanding-insights.md).
+
+![repositories tab](../../static/img/repos-insights.png)
+
+#### Contributors
+
+The Contributors tab allows you to view more detailed information on each contributor, including Activity, Repositories, the date of their last contribution, Time Zone, and the number of contributions.
+
+To learn more about your contributors, you can select them and add them to a list.
+
+![contributors insight list](../../static/img/contributors-insights.png)
+
+There are two ways to add contributors to a list:
+
+1. Create a new list with selected contributors.
+2. Add selected contributors to an existing list.
+
+## Lists: Connecting with Contributors
+
+OpenSauced Lists feature allows you to categorize, monitor, and analyze various groups of contributors. You can use Lists to track the contributions of a specific team, a specific repository, or a group of repositories. This feature offers granular insights into each contributor's activities and contributions, helping maintainers to track individual contribution histories, identify active engagement, recognize new or alumni contributors, and compare the performance of different contributors.
+
+The Lists features allow you to:
+
+- track the commits and PRs of the contributors on your list,
+- filter your contributors by their activity level, including most active, new, and alumni,
+- view the repositories that your contributors have contributed to, the top programming languages they've used, and their time zones.
+
+### Why Create a List?
+
+There are many reasons to create a list, but here's some inspiration to get you started:
+
+- **Interacting contributors**: Keep tabs on contributors actively interacting with your repository.
+- **Organization's developers**: Monitor the contributions and performance of your internal team.
+- **VIP contributors**: Highlight and track at least five developers who are key maintainers or significant contributors.
+- **Sales leads**: Identify contributors whose engagement could potentially be turned into sales opportunities.
+- **Potential hires**: Observe contributors who exhibit skill and commitment, making them prime candidates for hiring.
+- **Alumni contributors**: Keep an eye on contributors who have decreased their engagement or left the project.
+
+### Creating a New List
+
+1. Click the "Lists" tab on the Insights hub to create a new list. You will be redirected to a page where you can create your new list.
+2. Click on the "New List" button to start a new list.
+3. Give your list a name.
+4. Choose your page visibility. You can choose to make your list public or private. By default, it is set to private.
+5. Add contributors to your list by searching for their GitHub username, syncing your GitHub Team, or importing your GitHub Following.
+
+![team sync gif](../../static/gif/team-sync.gif)
+
+## Using Your List
+
+Once you have created your list, you will be redirected to your List Page. Here, you will see a dashboard with an overview of the contributors.
+
+There are three tabs that provide you with more information on these repositories:
+
+### Overview
+
+The Overview tab gives you a high-level view of the contributors in your list, including the total number of commits in the last 30 days and the types of contributors on your list: Active, New, and Alumni.
+
+### Activity
+
+The Activity tab gives you a graph view with more detailed information on each contributor, including the type of activity, repositories they've contributed to, and how they compare to each other.
+
+You can filter your list by All Contributors, Active Contributors, New Contributors, and Alumni Contributors.
+
+![list graph](../../static/img/list-graph.png)
+
+### Contributors
+
+The Contributors tab gives you the list of the contributors and includes information like activity level, last repository contributed to, the date of their last contribution, time zone, programming languages used, and number of contributions.
+
+To learn more about these features, see [Understanding Lists Data](understanding-lists-data.md).
+
+## Highlights: Connecting and Recognizing Contributions
+
+Leveraging OpenSauced's Highlights feature is a great way for maintainers to recognize and showcase the valuable contributions made to your open source projects, to curate and share key achievements, contributions, and milestones, and bring visibility to the hard work of your community.
+
+Highlights can be used to:
+
+- publicize issues on your repository that you'd like to match with contributors,
+- share Dev.to blog posts you've written,
+- celebrate PRs for your project.
+
+### Creating a New Highlight
+
+There are two ways to create a new highlight:
+
+1. After clicking the [Highlights tab](https://app.opensauced.pizza/feed) in the top navigation, click the input that says "Post a highlight to show your work!"
+
+2. From your profile, click the input that says "Post a highlight to show your work!"
+
+After you've clicked the input, you'll see a form that allows you to create a new highlight.
+
+There are two ways to create a highlight:
+
+1. Paste the URL to your PR, Issue, or Dev.to blog post (shown in blue below).
+2. Choose from a list of suggestions (shown in orange below).
+
+![highlight suggestions](../../static/img/highlights.png)
+
+If you're adding a blog post, you'll need to associate it to a repository by clicking the "Add a repo" button.
+
+Finally, it's time to add the details of your highlight. You can add a description yourself or use the auto-summarize function to generate a description.
+
+![gif of creating a highlight](../../static/gif/highlight.gif)
+
+### Writing an Effective Highlight
+
+Writing an effective highlight is key to attracting contributors to your project. Here are some tips to help you write an effective highlight:
+
+#### Highlighting Issues
+
+1. **Focus on the problem solved**: Begin by briefly describing the problem or challenge the issue addresses. This sets the context for why it was important.
+2. **Acknowledge contributor(s)**: Mention the contributor(s) who reported or worked on the issue, recognizing their effort.
+3. **Impact statement**: Explain how resolving this issue benefits the project, such as improving functionality, user experience, or security.
+
+#### Highlighting PRs
+
+1. **Summarize the changes**: Start with a clear summary of what the PR achieves. This could be a new feature, bug fix, or enhancement.
+2. **Credit the contributors**: Acknowledge everyone who contributed to the PR, including reviewers.
+3. **Highlight the value**: Explain the value of these changes to the project or its users. For instance, how it improves performance, adds a requested feature, or simplifies the codebase.
+
+#### Highlighting Dev.to Blog Posts
+
+1. **Capture the essence**: Begin with an interesting blog post summary, capturing the main theme or message.
+2. **Discuss the relevance**: Explain why this blog post is important for your open source project or community. Is it about a major update, a community event, or sharing best practices?
+3. **Engage with a call-to-action**: Encourage readers to engage with the post, whether by reading, commenting, or sharing their thoughts on the topic.

docs/maintainers/understanding-insights.md

@@ -0,0 +1,54 @@
+---
+id: understanding-insights
+title: 'Understanding Insights Data'
+sidebar_label: Understanding Insights Data
+keywords:
+  - maintainers
+  - guides
+---
+
+Once your repositories are connected, it's time to understand the data provided in your Insight Page. Understanding this data is key to effectively managing your projects and contributors.
+
+## Understanding Insights Repository Data
+
+### Analyzing Contribution Trends
+
+Discover patterns in contributions over time. Look for spikes or drops in activity and correlate these with specific events or milestones. This can help you understand what drives engagement in your projects.
+
+### Monitoring Pull Request (PR) Activity
+
+Knowing the status of PRs (open, closed, draft, merged) helps in understanding the workflow efficiency and backlog. High volumes of open or draft PRs might indicate a need for more resources or a revision of your review process. Conversely, a steady flow of merged PRs can indicate a healthy, active development process.
+
+### Measuring and Improving PR Velocity
+
+Track how quickly PRs are being merged. The average time taken for PRs to merge is a critical metric for understanding the efficiency of the code review and deployment process. Longer PR merge times might signal issues in the review process, resource allocation, or could indicate complex code changes that require more thorough checks. Use this data to set benchmarks and identify opportunities for streamlining your review and integration processes.
+
+## Understanding Insights Contributor Data
+
+### Identifying and Engaging with Key Contributors
+
+Recognizing key contributors helps in understanding the project's most active and influential members. Consider reaching out to them for deeper collaboration or acknowledging their efforts to keep them motivated and engaged.
+
+### Tracking and Responding to Contributor Activity Levels
+
+Tracking how active contributors are and the trends in their activity levels is crucial for project health. Understanding the activity patterns of contributors helps in assessing their engagement and reliability. Regular contributors are often more familiar with the project and can be more dependable for critical tasks.
+
+Notice the ebbs and flows in individual contributors’ activity. A decline in a normally active contributor’s engagement could indicate burnout or dissatisfaction, while a surge in activity might be tied to recent changes or enhancements in the project. Tracking activity levels can help you manage team burnout, understand resource needs, and spot potential issues before they escalate.
+
+### Activity Levels Across Repositories
+
+This indicates the breadth of a contributor's involvement in open source projects. A contributor active across multiple repositories might bring diverse experiences and ideas but may also have divided attention. Alternatively, a contributor active in a single repository might be more focused and familiar with the project.
+
+### Understanding Activity Levels Over Time
+
+Past activity levels can be a predictor of future contributions. Regular past contributions might suggest continued involvement. However, a contributor who has been inactive for a while might be less likely to contribute in the future.
+
+Trends in activity levels and contributions can be indicators of the overall health of the project community. A decline in activity might signal issues that need addressing to keep the community vibrant and engaged.
+
+### Using Programming Language Data
+
+Awareness of the programming languages a contributor is comfortable with enables maintainers to assign tasks more effectively, ensuring that contributors work in areas where they are most skilled and interested. This can help in identifying contributors for specific tasks or projects.
+
+### Creating Opportunities
+
+Understanding who contributes to what open source projects and when they do can help maintainers manage team dynamics. With this information, maintainers can make decisions to ensure workloads are balanced and contributors are working in areas that match their skills and interests. Identifying less experienced contributors who are active and showing potential can lead to mentorship opportunities, helping to grow the project’s contributor base.