Reworking Coop docs for 1.0

[cassidyjames]

Hey Coop contributors! I've been having a lot of conversations about Coop with potential adopters, which has meant I've been scouring the docs to look up information and provide relevant links. In doing this, I've come up with my own sort of approach for how I walk through what Coop is and its capabilities/design.

What I'm wondering now: would this layout be an improvement to the docs, either overall or for the user/adopter guide? I'd be signing myself up for a pretty substantial rework of the documentation, so I wanted to check in with you all first and get any feedback.

Current structure

1. Welcome (contributor-oriented)
   • Getting started
   • Reporting issues
   • Need help?
2. Concepts (developer-oriented)
   • Item
   • Action
   • Policy
   • Reports
   • Appeals
   • Users
3. Development
   • Local development guide
     • Prereqs
     • Env setup
     • Docker services
     • Database operations
     • Running the app
     • Testing
     • GraphQL dev
     • HMA dev
     • Troubleshooting
     • Code quality
   • Architecture
     • Tech stack
     • Directory structure
     • API
     • Rules engine
     • Manual review tool
     • Actions
     • Storage
     • Signals
     • Action Rules vs Routing Rules
     • Authentication
   • Integrating signals
   • Integrations plugin
   • Data warehouse abstraction
4. User guide (largely admin-oriented)
   • User interface
     • Dashboard
     • Settings
     • Policies
     • Manual review
     • Investigation
     • Automated enforcement
     • Appeals
     • Recent decision log
     • NCMEC review/reporting
   • API keys/auth
   • Rules
   • Reports
   • Appeals
   • NCMEC reporting

Proposal

My overarching thought is to a bit more clearly split the docs into product-focused, developer-focused, and integration-specific documentation. I think a lot of the developer docs would remain as-is, but could be reorganized a bit. The user guide would be more largely reorganized and broken down to focus on product features first, rather than being so monolithic and both technical and UI-focused (though I imagine we'd keep all the nice screenshots as references where they make sense!). Finally, the integrations section would pull out the relevant information for specific built-in integrations so it's less scattered throughout.

I imagine it being structured something like:

1. Product guide: focused on documenting functionality, not on implementation details
   1. Overview of Coop
   2. Automated routing & enforcement
      • Text banks
      • Hash banks
      • Location banks
      • Integrations
   3. Manual review & enforcement
      • Queues
      • Context included
      • Wellness features
      • Policy-based
      • Actions
   4. Investigation
   5. Bulk actioning
   6. Appeals
   7. Metrics/reporting
      • Recent decisions log
   8. Administration
      • Policies
      • User management
      • Single sign-on
2. Development guide: technical docs focused on local development and understanding the codebase
   • Getting started
   • Concepts & Architecture
   • Contributing
   • (Still working through this structure… but imagine it's largely the same content to start, maybe just reorganized/broken down a little more clearly)
3. Integrations guide: focused on specific built-in integrations, their capabilities, and configuration
   1. Built-in integrations
      1. Google Content Safety API
      2. OpenAI Moderation API
      3. Hasher-Matcher-Actioner
      4. NCMEC Reporting
      5. Zentropi
   2. Model cards
   3. Bring your own

Something else that's been raised as potentially helpful is a "deployment guide," which I think could be its own top-level section as well—focused on getting Coop running with your platform, on common infrastructure targets like bare metal, AWS, Azure, etc. But I left that out for the moment since it's its own undertaking.

Feedback!

Please let me know what you think about this reworking; I want to make sure I'm not missing anything and that the structure doesn't seem totally off!

[julietshen]

Thank you for taking this on!

This mostly looks good to me, but I would make a few changes:

• Routing rules should stay with manual review, in my head it's tightly coupled and part of how users think about review queues
• HMA should be under integrations
• Zentropi needs to be added to the integration section
• maybe add something about model cards to the docs?
• Under metrics/reporting, include the recent decisions log and the fact that it can be exported for Transparency Reporting or QA

[cassidyjames]

Ack; I've updated the integrations and metrics/reporting sections. Gonna think about the routing rules and model cards bit but I hear you.

[cassidyjames]

Added model cards under the integrations guide; it could be its own page or just part of the top-level page for the section depending on length.

[H-Shay]

FWIW I found the Concepts section to be the most helpful in thinking about how to use Coop in the context of our system vs develop it - if it's moved to the Developer section I think it'd be nice to reference/link it/suggest that potential adopters who might not consider themselves developers check it out somehow.

[cassidyjames]

Thank you, that's super helpful feedback! This also sort of lends weight to the idea of a "deployment" guide that's distinct from developer docs. I'll continue noodling on that. :)

[cassidyjames]

I've started work on this in #338, but I think I was a bit overambitious in trying to get it done in one pass. 😅 I'm going to still follow the overall structure laid out above, but I'm breaking it into smaller chunks/steps to hopefully iterate more quickly so we can get refreshed docs out in time for a v1 release.

Something I want to look into as well: versioned docs. I've been hesitant to merge things in since it will break existing links to docs which adopters might be actively using; instead it'd be nice if they had stable v0 docs while we could iterate on the main docs. Two solutions I see:

1. Full-on docs versioning, either:
   • using a custom workflow to grab docs from each tag and put them into GitHub pages paths manually, still using mdbook, or
   • switching to a doc generator that supports this natively
2. Only update the docs site on a tag/release instead of always tracking main

The second is probably the quicker solution, but also adds overhead to actually shipping docs updates. Still, I'm leaning towards that for now with the first solution as a longer-term ideal.

[cassidyjames]

I was hoping VitePress would save us with built-in versioning support, but alas, no. It looks like it would be the same approach as using mdBook: manually crafting a GitHub Actions workflow for building the versioned directories (which honestly: not that hard!), or maintaining the versioned docs directly in the repo. I lean towards the former as it keeps the docs in the repo directly relevant to the code in the same checkout.

[cassidyjames]

I opened an issue to track versioning the docs at #415

[cassidyjames]

Big update:

• Versioned docs are in, and live at https://roostorg.github.io/coop
• docs: Rework for v1 #338 is ready for review

+5,258 / -2,055 lines changed across 52 files and 55 commits. 13 issues addressed. It's… a lot.

The good news is that we’re gonna have some great docs, plus I know a lot more about Coop than I did before. 😆

#338

[H-Shay]

Drive-by comment because this just popped into my inbox: I've been meaning to ask if there could be some docs about how distributed logging/otel/jaeger works in the system - I have been trying to parse it out for myself but it'd be nice to have some sort of overview to work from in the docs. Just a nice-to-have!

[cassidyjames]

@H-Shay thanks for dropping by! :) Sorry if my comments were spamming you via email. 😬 I filed this at #416 so it doesn't get lost. Thank you for flagging the request!

[cassidyjames]

The docs rework has been merged into main and is live! The previous docs are still available at /0.1.

I will continue combing through the latest docs and filing issues/PRs to follow up with anything else I find. Please feel free to file any follow-up issues as well, or you can hit the ✏️ edit icon in the header to make a quick fix as a PR.

I'd especially love for any adopters (@H-Shay, @ThatKoffe, @jess-upscrolled, @calebmcquaid, anyone else) to take a peek and let me know your feedback. 🙏