Documentation should be “sip-first”

[julienrf]

Describe what needs to be done and why

Currently, the website documents the scala command in a small subsection that assumes that the users are familiar with the extra features brought by scala --power. As a consequence, the documentation on how to use scala is not self-contained and more complex than necessary.

Instead, the website should document the stable features first, and mention anything available under --power in extra sections.

[tgodzik]

Thanks for reporting! Only now getting back to it. I think Scala-Cli website should have a subsection with how the actual self contained Scala runner documentation would look like. We can then host that somewhere else. What do you think?

@romanowski had some ideas about it

[julienrf]

I think the self-contained documentation about the scala runner should not be a subsection in the Scala CLI website, but the website (with some side-sections about the --power / --experimental features). (Maybe I misunderstood your comment)

[tgodzik]

I meant that this subsection would be then hosted somewhere else as standalone. So the docs would be generated within scala-cli repo and then deployed elsewhere as a single page.

[tgodzik]

The summary of what we discussed and decided:

1. We should only have one Scala runner and that should be ScalaCLI
2. This means we will have main documentation page similar to how cargo has a separate one. It might be linked from scala-lang page.
3. All the non-default (power commands) will be marked a such with a clear annotation of why they are experimental and how to unblock them.