docs: refactor data model and impact metrics sections (#1152)

apps/docs/docs/how-oso-works/challenges/_category_.json → apps/docs/docs/contribute/challenges/_category_.json

@@ -1,6 +1,6 @@
 {
-  "label": "Data Challenges",
-  "position": 6,
+  "label": "Join a Data Challenge",
+  "position": 7,
   "link": {
     "type": "doc",
     "id": "index"

apps/docs/docs/contribute/index.mdx

@@ -47,5 +47,11 @@ There are a variety of ways you can contribute to OSO. This doc features some of
 <td>Contribute to our library of data visualizations and Jupyter notebooks.</td>
 <td>Data Scientists, Analysts</td>
 </tr>
+<tr>
+<td>Join a Data Challenge</td>
+<td><a href="https://github.com/opensource-observer/insights">Insights</a></td>
+<td>Work on a specific data challenge and get paid for your contributions.</td>
+<td>Data Scientists, Analysts</td>
+</tr>
 </tbody>
 </table>

apps/docs/docs/contribute/project-data.md

@@ -55,14 +55,14 @@ If you run into issues, check out [GitHub's instructions](https://docs.github.co
 - If the project doesn't exist, you can create a new `.yaml` file under `./data/projects/` In most cases, you should simply use the GitHub organization name (eg, `my-new-org`) as the slug and filename (eg, `./data/projectsm/my-new-org.yaml`).
 - If the project is not associated with a GitHub organization, you can use the project name followed by the repo owner as the slug, separated by hyphens (eg, `my-repo-my-org`), and the same convention for the filename (eg, `./data/projects/m/my-repo-my-org.yaml`).
 - Initialize the new project with the following fields:
-  - `version`: The version of the schema you are using. The latest version is Version 3. You can learn more about the schema [here](../how-oso-works/data-model/schema-updates).
+  - `version`: The version of the schema you are using. The latest version is Version 3. You can learn more about the schema [here](../how-oso-works/oss-directory/schema-updates).
   - `slug`: The unique identifier for the project. This is usually the GitHub organization name or the project name followed by the repo owner, separated by hyphens.
   - `name`: The name of the project.
   - `github`: The GitHub URL of the project. This is a list of URLs, as a project can have multiple GitHub URLs. In most cases, the first and only URL will be the main GitHub organization URL. You don't need to include all the repositories that belong to the organization, as we will automatically index all of them.
 
 ### 3. Link artifacts to the project
 
-- Add artifacts to the project file. Artifacts are the different types of data that we index for a project. You can find the list of artifacts in the [schema](../how-oso-works/data-model/artifact). Here's an example of a project file with artifacts:
+- Add artifacts to the project file. Artifacts are the different types of data that we index for a project. You can find the list of artifacts in the [schema](../how-oso-works/oss-directory/artifact). Here's an example of a project file with artifacts:
 
   ```yaml
   version:

apps/docs/docs/contribute/share-insights.md

@@ -31,9 +31,9 @@ Most of our visualizations are generated in Python using Matplotlib, Seaborn, an
 
 Contribute your own data visualization templates by adding them to the `./visualizations/` directory in the Insights repo. Please include a docstring in your visualization script explaining the expected data format and a brief description of use cases.
 
-### Impact Vectors
+### Impact Metrcs
 
-We're building scripts and analysis frameworks for community-generated impact vectors. Submissions must be replicable with data sourced entirely from the OSO data warehouse and should follow the follow the [Impact Vector Specification](../how-oso-works/impact-vectors/).
+We're building scripts and analysis frameworks for community-generated impact metrics. Submissions must be replicable with data sourced entirely from the OSO data warehouse and should follow the follow the [Impact Metrics Specification](../how-oso-works/impact-metrics/).
 
 In most cases, impact vectors will be reviewed and recognized via one of our Data Challenges, with separate instructions for showcasing work and submitting pull requests.
 

apps/docs/docs/how-oso-works/data-model/event.md → apps/docs/docs/how-oso-works/event.md

@@ -1,12 +1,20 @@
 ---
-title: Event
-sidebar_position: 5
+title: Event Data Indexers
+sidebar_position: 3
 ---
 
 :::info
 An **event** is a record of a transaction or other activity involving an artifact, or a snapshot of cumulative events at a given point in time. Events are used to track the history of an artifact.
 :::
 
+## Overview
+
+---
+
+Every event is associated with an artifact that belongs to a single project. For example, a GitHub commit event is an event `from` a GitHub user artifact `to` a GitHub repo artifact owned by a single project. Similarly, a blockchain transaction event would be an event `from` a blockchain address artifact `to` another blockchain address artifact owned by a single project.
+
+The `to` and `from` relationships between artifacts in an event are critical to OSO's ability to understand the impact of a project's activities and situate it in the context of overall network / ecosystem activity.
+
 ## Event Types
 
 ---
@@ -44,11 +52,3 @@ All blockchain events are associated with a unique blockchain address-network pa
 - Contract Invocation Daily Count: A snapshot of the number of transactions made with a contract address on a given date.
 - Contract Invocation Daily Fees: A snapshot of the fees paid for transactions made with a contract address on a given date.
 - Users Interacted: A snapshot of the number of unique users (addresses) transacting with a contract address on a given date.
-
-## Querying Event Data
-
----
-
-The event table is the largest table in the OSO Data Warehouse. As such, we have created data marts that aggregate event data at daily, weekly, and monthly intervals for artifacts, projects, and collections.
-
-As event queries may be slow, we recommend using these aggregate tables whenever possible. See the [API documentation](../../integrate) for more information about querying event data.

apps/docs/docs/how-oso-works/impact-metrics/github_activity.md → apps/docs/docs/how-oso-works/impact-metrics/code.md

@@ -2,10 +2,10 @@
 sidebar_position: 2
 ---
 
-# GitHub Activity
+# Code
 
 :::info
-GitHub metrics include repo histories, popularity indicators, and work activity. GitHub metrics may be queried by project (eg, `uniswap`) or by repo (as an artifact) in the format (eg, `repo-owner/repo-name`). For additional information about GitHub data, also see: [GitHub Contributors](./github_contributors)
+GitHub metrics include repo histories, popularity indicators, and work activity. GitHub metrics may be queried by project (eg, `uniswap`) or by repo (as an artifact) in the format (eg, `repo-owner/repo-name`).
 :::
 
 ## Repository Metrics
@@ -60,6 +60,38 @@ The number of pull requests opened in the project's repositories in the last 6 m
 
 The number of pull requests merged in the project's repositories in the last 6 months.
 
+## Contributors
+
+---
+
+Contributors are GitHub users who contribute commits, issues (opened/closed), and pull requests (opened/merged) to one or more of a project's code repositories.
+
+### contributors
+
+The total number of contributors across all the project's repositories.
+
+### contributors_6_months
+
+The number of contributors who have contributed to the project's repositories in the last 6 months.
+
+### new_contributors_6_months
+
+The number of new contributors to the project's repositories in the last 6 months.
+
+## Developers
+
+---
+
+A developer is a contributor who commits code to the main branch of one or more of a project's repositories. Our definitions for full-time and part-time developers are intended to align with the methodology used by Electric Capital in their [Developer Report](https://www.developerreport.com/about).
+
+### avg_fulltime_devs_6_months
+
+The average number of full-time developers working on the project's repositories in the last 6 months. A full-time developer is defined as a contributor who has made commits to main on at least 10 days in a given month.
+
+### avg_active_devs_6_months
+
+The average number of active developers contributing to the project's repositories in the last 6 months, including both full-time and part-time developers. An active developer is defined as a contributor who has made commits to main on at least 1 day in a given month.
+
 ---
 
-To contribute new metrics, please see our guide [here](../../contribute/impact-models)
+To contribute new metrics, please see our guide [here](../../contribute/impact-models).

apps/docs/docs/how-oso-works/impact-metrics/dependencies.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 7
+sidebar_position: 5
 ---
 
 # Dependencies

apps/docs/docs/how-oso-works/impact-metrics/onchain_activity.md → apps/docs/docs/how-oso-works/impact-metrics/onchain.md

@@ -1,8 +1,8 @@
 ---
-sidebar_position: 4
+sidebar_position: 3
 ---
 
-# Onchain Activity
+# Onchain
 
 :::info
 Onchain metrics include projects' smart contracts, transaction volumes, and sequencer fee contribution. Onchain metrics are typically queried by project (e.g., `uniswap`) and network (e.g., `optimism`), but they can also be queried by contract address (e.g., `0x123...`) and even across networks (e.g., `optimism` and `arbitrum`).
@@ -12,7 +12,7 @@ Onchain metrics include projects' smart contracts, transaction volumes, and sequ
 
 ---
 
-For information about how addresses are tagged, please see: [Address Tagging](../data-model/artifact.md#tagging-addresses).
+For information about how addresses are tagged, please see: [Address Tagging](../oss-directory/artifact.md#tagging-addresses).
 
 ### num_contracts
 
@@ -34,8 +34,6 @@ Open Source Observer only tracks transactions that involve smart contracts, as m
 
 Our primary focus is on transactions between externally owned account (EOA) addresses and smart contracts. We do not currently track the internal transactions between smart contracts, although their effects are captured in the aggregate transaction costs of the EOA to smart contract transactions. We also do not track transactions between EOAs, even though these are often facilitated by a frontend or wallet interface, because that information is not captured onchain.
 
-For additional information about onchain user data, also see: [Onchain Users](./onchain_users).
-
 ### total_txns
 
 The total number of onchain transactions with the project's contracts.
@@ -60,6 +58,46 @@ The total Layer 2 gas used by the project's contracts.
 
 The total Layer 2 gas used by the project's contracts in the last 6 months.
 
+## Users
+
+---
+
+### total_users
+
+The number of unique addresses interacting with the project's contracts.
+
+### users_6_months
+
+The number of unique users interacting with the project's contracts in the last 6 months.
+
+### new_users
+
+The number of users interacting with the project's contracts for the first time in the last 3 months.
+
+## Active Users
+
+---
+
+### active_users
+
+The number of users interacting with the project's contracts in the last 3 months.
+
+### high_frequency_users
+
+The number of active users who have made 1000+ transactions with the project's contracts in the last 3 months.
+
+### more_active_users
+
+The number of active users who have made 10-999 transactions with the project's contracts in the last 3 months.
+
+### less_active_users
+
+The number of active users who have made 1-9 transactions with the project's contracts in the last 3 months.
+
+### multi_project_users
+
+The number of users who have interacted with 3+ projects' contracts in the last 3 months.
+
 ---
 
-To contribute new metrics, please see our guide [here](../../contribute/impact-models)
+To contribute new metrics, please see our guide [here](../../contribute/impact-models).