Revamp documentation resources

lampepfl / gears

A strawman for a low-level async library in Scala 3.

https://lampepfl.github.io/gears/

Apache License 2.0

247 stars 24 forks source link

Revamp documentation resources #54

Closed natsukagami closed 5 months ago

natsukagami commented 6 months ago

Most documentations live in /docs now, with a landing page at https://lampepfl.github.io/gears linking to them.

README now is a simple page showing build status, release, basic build instructions etc.

Move Bartosz's report to its own directory
Move Martin Odersky's talk and README to docs
Add Maximilian's report
Add landing page
Add a simple README

m8nmueller commented 5 months ago

I wonder what's the role of the README in this setup: Build instructions are in CONTRIBUTING and infos - or rather: links - are on the docs page. If the page didn't look as nice as it does, I would have voted for its deletion in favor of an elaborate README. But I guess it's fine, because it does look nice :)

Besides, I would add some "For an overview of the library, see..." which would be really important to be in the docs imho. We do have something like that: the release notes: https://github.com/lampepfl/gears/releases/tag/v0.1.0. Maybe we could copy/move them to the docs - and in any case keep them updated. Otherwise it's very hard to get started, given the reports, the Scala API, and the increasingly outdated Scalar README.

amsen20 commented 5 months ago

I think it would be better to have more parts on the README even if they are available somewhere else, the following are the parts I find useful:

An overview part describing the library's positive points compared to existing Scala async programming libraries (like structured concurrency and simplicity)
A "Getting Help"/"Where to Start" part with a link to the library main page in docs (I think it is essential)
An Example part explaining a quick example of how to add gears to a project and an example of simple code.

In my opinion, the README of the following pages looks fine to me and is similar to gears (in some way :D):

tokio
trio (especially the description part)
rayon (the description and example)
embassy

The page is great. I think the library is better to have its own logo :D

natsukagami commented 5 months ago

Besides, I would add some "For an overview of the library, see..." which would be really important to be in the docs imho.

Would the book be sufficient in this case?

natsukagami commented 5 months ago

Let's have this in first -- I think it's better to have a landing page first and foremost, better than nothing ;) We can improve it later.