typelevel / typelevel/cats-effect

CE3 Documentation Mega-TODO List

Open
#1,715 4 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

:books: docs 🥺 help wanted
Dominant language
Scala
Stars
2.2k
Forks
576
Avg merge
2d 11h
Merged PRs (30d)
18

Description

It's a little easier to consolidate these things into one place. Structuring things based on the sidebar:

  • Overview
    • Need a beginner-friendly explainer of what IO is
    • Performance page touching on some top-line general numbers and concepts
    • Tracing documentation
  • Getting Started (this whole section should probably just be ported from CE2's microsite, because the walkthrough and topic is good)
  • Best Practices (this should be a section covering best practices on how to structure your applications, ways to solve certain problems like dependency injection, etc; general "leveling up" stuff)
  • Standard Library
    • Console
    • Random
    • Some of the articles in this section also need a bit of cleanup for consistency
  • Ecosystem (I'm envisioning this as a use-case focused section with entries for "Http" (subsections "Client" and "Server"), "Kafka", etc; mostly just linking to external libraries and maybe giving a quickly copy/pasteable snippet for sbt and call-site)
  • Scaling and Tuning (advice for how you run Cats Effect-powered services at scale and what it means to tune them for high load)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

The issue is a broad documentation backlog organized by the sidebar, covering Overview, Best Practices, Standard Library, Ecosystem, and Scaling and Tuning; Getting Started is marked complete and should be ported from CE2's microsite. Begin by selecting and separately scoping one unchecked section or article. Done is not defined for the mega-list as written, so a contributor needs a concrete subsection and acceptance criteria first.

Written by the indexing model from the issue text.

Assessment

Tech stack
scala
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.