Brainstorming around documentation

[jducoeur]

At the moment, we don't really have any good getting-started documentation on the Typelevel website, and we need some.

So here's a thread for discussing what we should have there. This is explicitly brainstorming: while it's fine to engage in a little give-and-take, please keep it constructive, and build on each other's ideas. Nothing here is going to be final decisions -- this is all about starting to organize our thoughts.

(This is specifically about the "what", not the "how". Once we have some idea of what documentation we would like, then we can talk about how we get there from here.)

This is intentionally open -- viewpoints from relatively new folks on "this is what I wish I'd found here six months ago" are just as valuable as those from old-timers who are building the libraries. So please chip in with your ideas!

[rossabaker]

One thing any documentation revival in 2024 needs to reckon with is Scala 2 vs. Scala 3.

• Scala 2 examples mostly work unaltered in Scala 3
• Targeting Scala 2 is unidiomatic for the slowly-but-surely growing number of Scala 3 users
• That number is currently in the vicinity of 30% (crude sample of download stats) to 50% (VirtusLab survey)

Tabs with both are possible, but twice the code to maintain.