docbrown/config/feed

Feed Configuration

Welcome to the technical documentation of the Feed Configuration. In this document we'll introduce the historical context, provide a glossary of terms, delve into the high-level goals of the configurations, and describe any present constraints.

Historical Documents

• The Articles::Feeds::WeightedQueryStrategy is the precursor to the more robust feed configuration. It provides hints as to how we'll structure the feed configuration.
• These Are the [Feed] Levers I Know I Know - Forem Team 🌱
• Creating a Catalog of Feed Levers and Configurations - Forem Team 🌱
• On <2022-04-11 Mon>, Jeremy, Jennie, Ella, and Michael T met over Zoom to talk through the current feed.

Glossary

• Feed Experiment: A feed experiment is the currently implemented set of feed strategies - current configurations we're using to generate feeds
• Feed Strategy: a configuration of levers and relevancy factors, which can be used to generate the relevancy feed.
• Lever: A lever is a specific attribute we're querying from the database.
• Lever Range: The lever range is the potential range of values that the underlying lever query will emit; for example integers greater than or equal to 0.
• Relevancy Factor: The relevancy factor maps the lever range to a rational number between 0 and 1.
• Relevancy Feed: The relevancy feed (or for this document the feed) builds the list of articles a user sees on the homepage of a Forem.
• Relevancy Score: Each article is assigned a relevancy score based on the lever configuration of the current feed strategy. It is the product of all applicable relevancy factors for each of the levers in the feed strategy.

At a future point, we might allow for the site creators to pick one or more feed strategies for the relevancy feed and even allow a member to specify their feed. It is possible that we would adjust the UI so that the feed formats (Relevant, Recent, and Top) also include things like "Active Discussions" or other emergent feed strategies.

Configuration

There are three layers of configuration, presented working from the inside out.

1. Lever
2. Feed Strategy
3. Feed Experiment

Lever Configuration

Each lever requires engineering time to create and define. This involves:

• Defining the programmatic key for the lever.
• Writing the human readable label.
• Describing the purpose of the lever.
• Creating the SQL clause fragments (e.g. select, optional joins, and group by), and documenting the lever range.
• Defining if this is a lever that requires the user to be signed in.

This may also require adding new variables that we pass to the SQL parameter substitution process. (see Experience lever factor).

I believe the goal is to avoid changing the SQL implementation details of a lever; we would instead create a new lever. This way we can have consistent documentation for a given lever.

Feed Strategy

Each feed strategy need not require engineering time to create and define. This involves:

• Defining the programmatic key for the feed strategy.
• Writing the human readable label.
• Writing any notes around the feed strategy.
• Defining which lever this feed strategy incorporates.
• For each lever,
  • Mapping the elements within the lever range to the desired relevancy factor.
  • Defining the fallback relevancy factor.
  • Describing the intention of this mapping and fallback.

From an application stand-point we want to run the queries for each feed strategy (to ensure valid SQL).

Feed Experiment

At any given time, we are running one feed experiment. The feed experiment comprises one or more feed strategies and defines the probability of a user being assigned to each of those feeds; see our AbExperiment. We will need to uniquely name each feed experiment so we can collectively document both intention and observations.

Environments and Constraints

This section outlines the current (as of <2022-04-12 Tue>) constraints of the system.

While the application is running, either in production or under a request or integration test, we should only load feed strategies that are part of a feed experiment and/or available for a Creator to select.

To expose a new feed strategy to a production instance will require a deploy of that instance. At a future point, we may look to allowing uploads of feed strategies but that is not the current path.

Changing from one feed experiment to another will require a new deploy. At a future point we might allow for live changes of the feed experiment but that is outside the scope of present considerations.

Each feed strategy will be tested as part of unit testing; to ensure it generates valid SQL.

Each feed lever will be tested as part of unit testing to ensure it is well crafted.

One consideration is that the relevancy feed should include a published_at constraint. This can generate a large and potentially expensive query, so we want to discard older articles from the relevancy.

What is the recommended size of that published_at constraint? It is a function of the average number of posts per week. A more active Forem, such as DEV would want to limit this published_at constraint to around 2 weeks. A less active one could limit to 2 months.