interop-cats VS mdoc

If you're using http4s, don't use ZIO. Yes, ZIO has an interop-cats module, so you can do this. But using http4s means you're working in the conceptual framework the Typelevel ecosystem is based on (and what interop-cats does can be characterized as "describe ZIO's implementation in those terms, so the Typelevel ecosystem can make heads or tails of it.") This is essentially all cost and no benefit: you can't avoid understanding the Typelevel ecosystem if you use http4s (at least, no more than you can by using cats-effect), and you don't get any of the value proposition of ZIO (interop-cats gives you Typelevel typeclass instances for the RIO type alias, which means your error channel is rooted in Throwable, and you're faced with the most complex part of the ZIO ecosystem: ZLayer, which the Typelevel ecosystem doesn't use and doesn't need). Finally the ZIO ecosystem is still quite immature, and this brings us to documentation. There is not (yet!) anything comparable to:

These are necessarily oversimplifications. In particular, the ZIO ecosystem offers the relevant instances of cats-effect typeclasses to support use of the ZIO type in the cats-effect ecosystem.

However, ZIO continues to offer cats-effect type classes and I certainly have no doubt cats-effect 3 continues to benefit from John's contributions. Furthermore, I likewise don't doubt the value of the ZIO ecosystem generally, and John's success in building the ZIO community speaks for itself. I personally have chosen to remain closer to the other, let's say "classical," pure FP ecosystems, partially for historical (or, if you prefer, "sunk cost") reasons, but partially because I'm satisfied the value of the Haskell/Typelevel/PureScript/fp-ts/etc. interplay warrants it.

It seems that zio/interop-cats faces a similar issue.

Literally what scaladoc is, it comes with sbt. Although, it's better when enhanced with mdoc so that you get the standard microsite template like these. It would be nice to have an sbt serveDocs and if everyone would host their docs for external linking, but javadoc doesn't do that either.

The good news is that scaladoc is produced by default by sbt and published by default. So you can often pull it from the same repository your library jar came from, extract it with zip, and read the docs. But that's also totally unnecessary - javadoc.io allows you to put in your module info and serves the docs for you, so if there's an older version you can access the documentation this way. Rely on the type signatures, since they can't lie, whilst comments (including scaladoc comments) can. Honestly, library authors should be using mdoc and including examples on every public method, and that type of documentation is something you can almost always contribute to a project for a quick pr kudos.

I know it's not new but the "Snippet validation and results (mdoc)" features in mdoc are so cool. Really takes some of the tedium out of working with documentation since you can know that as you evolve your code the compiler will make sure you keep the docs in sync. Whole new level of Readme-Driven Development