Collaboration Design Document

[alexkim205]

Collaboration Design Doc

Internal Milestone Issue

Balsamiq Wireframes

This issue serves as a living design document that also tracks any decisions and findings made throughout the Collaborations project. Tagging @paolodamico, @clarkus, @mariusandra, @EDsCODE for context and general feedback.

Problem

Over the past few months, we've put a lot of work (see Saved Insights) into refactoring saved insights and dashboards into standalone entities in the app. However, there is no natively supported way to share these insights, more or less share them with purpose and context. This product gap has several disadvantages:

1. Users spend less time in our app. Context sharing happens in third party channels. We don't bring the discussion into PostHog, which means less people see how awesome our product really is.
2. Users don't understand insights they themselves haven't made. Other teammates' learnings can't be leveraged, which makes it difficult to adopt PostHog.
3. Insights become difficult to understand and maintain. Saved insights and dashboards become a kitchen sink of information that becomes overwhelming at large scales. Case in point, our own insights.
4. There are workarounds but they're painful. Several of our large users share PostHog reports manually, either through email, screenshots on Slack, etc. There have also been requests for bots that generate and emit notifications on a timely cadence.

Requirements

• No breaking changes.
• Intuitive to use. Experience that's familiar to use and integrate everywhere.
• Secure. External collaboration opens the door to vulnerabilities. Ensure a clear separation of internal and external permissions.

Proposals

Today

Why can't we incorporate collaboration into our current features?

Today, if an internal team member wants to share an insight with another team member or external user, they have three options:

1. leverage the optional description metadata of an insight or dashboard to explain what is being shown and why it is important
2. share the longform PostHog link in an external channel (Slack, Teams, Notion, etc.) with an accompanied explanation
3. use {insight|global}-level annotations

All of these options are lacking and don't solve the core collaboration issue at hand.

1. Description metadata is an in-app solution to persisting some context about the insight, however users cannot capture historical or user specific context.
2. Sharing context outside of PH is more flexible, but PostHog loses the opportunity to capture context sharing within the app and leverage that. Additionally, deferring to other channels encourages users to leave the app to gain context which is a big retention no-no.
3. Our current implementation of annotations solves for another problem entirely. They're also only available for insights with time as their x-axes and generally not discoverable.

Tomorrow

Below we propose two new features.

Insight Discussions

Tomorrow's saved insight and dashboard pages will have an overlay that allows users to start discussion threads that are persisted company wide. Internal PostHog team members will be able to comment and cross-tag each other to engage in conversation or provide context for others that can easily be forgotten or buried. Conversations are persisted for the entire lifetime of an insight, which means that historical context is captured as an insight evolves with time.

Users deserve a rich and modern chat experience that updates/notifies users in real time (via sockets), allows tagging of other teammates, has a rich markdown experience, and more. However, PostHog does not have a well defined notifications system that these features can be built on top of (no, toast notifications don't count), and it must be built out as a prerequisite.

Task Breakdown

• Fully baked in notification system
  • Email and in-app notifications as MVP
• "Get team members" API and selector
• Real time message channeling
  • Client and server socket logic
  • Setup ASGI server (Daphne)
  • Setup django-channels
• Add comments into saved insight model
• Message panel and GUI
• Global app notification system
  • Might have to think about how this clashes with our current toast notification system.

Link Sharing

Tomorrow's link sharing experience is composed of two tightly coupled features: Permalink with integrations + a new Centralized Link Management page.

Task Breakdown

• Permalink with integrations
  • Use short ids in insight url's - @mariusandra https://github.com/PostHog/posthog/pull/7259
  • Concept of public and private dashboards/insights
    • What should or shouldn't be available to the public (i.e., person modal, date pickers, annotations, etc.)
  • Server-side public and private permissions
  • What kind of metadata should link previews be enriched with?
  • Capture link usage data with url refs (don't expose yet but for future use).
  • Cached image previews
  • Unique link generation with different parameters (expiration, password protection, explicit user permissions, etc.)
• Centralized Link Management
  • Table View with basic filters and activation toggles.
  • Link CRUD

Scope

This document proposes two solutions that solve two very specific problems. Insight discussions makes it easy to share insights with context. Managed link sharing makes it easy to create, share, and manage public and private links. Both make PostHog a more collaborative platform where conversations and cross linking can happen.

The following are considered out-of-scope. Some of these may be revisited in subsequent iterations of collaborations work.

• Meta Metrics (i.e., internal team usage, insight-specific metrics, link sharing metrics)
• Collaboration taxonomy (i.e., understanding event/property shapes, verifying & unverifying events, versioning)
• Education (i.e., conventions and best practices, feature tutorials, etc.)
• Integrations+, anything beyond rich link previews (i.e., Slack bots, feature rich webhooks)

Key Performance Indicator

Basic Sharing Events

• link generated - tracks every time shareable link is created. Each link is given it's own id
• link with referrer - tracks every time link is visited by clicking the shared link
  • includes referrer_url in event

_Engagement + Insight Discovery__

• insight views - This category's harder to measure because adding insight metadata won't trigger a new user behavior/state change that can be measured tangibly. I think a soft metric on this would be the observing how the number of views each saved insight changes after the feature is deployed, but open to suggestions.
• clicked recommended insight - tracks user clicking recommended insights. boom, insight discovered
• universal search opened/searched - tracks universal search usage with anonymized query parameters

Taxonomy Events

• event/property tags CRUD - tracks tag usage
• events deprecated/verified - tracks event versioning
• malformed event detection - tracking at the event ingestion level when bad events are handled (This might already be done but would have to double check)

Annotations Events

• annotations CRUD v2 - tracks new implementation of annotations

Onboarding Events

• meta-metrics viewed - tracks times that the meta metrics pages are viewed

Scaling Considerations

Section is WIP

One thing that comes to mind with scaling is the extra burden that socket connections from real time chats will have on the server.

[samwinslow]

Hey @alexkim205, love the amount of thought you've put into this, and the wireframes look great!

Could you elaborate a bit on how we'll define "Amount of time users spend on the app?" Is that average session length on app.posthog.com, or on one section of the app, or for a specific segment of users (insight creators vs. consumers)?

I'm also a bit confused as to how link sharing metrics are to be considered out of scope, yet references to them exist under KPIs.

[EDsCODE]

Thanks for giving this overview of the plan!

RE: real time messaging. I'd add that more subtle features such as a "currently viewed by" widget could help in effecting stronger sense of collaboration.

The two major focuses seem solid overall. I think a good next step (or maybe it exists somewhere and I didn't see it) would be an execution plan that describes how these line items can be bundled together/ordered to be implemented.

[paolodamico]

I think this has now a lot of duplicated scope with #7244, should we maybe close the other one and continue the conversation here?

[paolodamico]

@alexkim205 I think a lot of the scope here has evolved, should we close this?

[alexkim205]

Yup a lot's changed since this was made, let's close this