Add working "get started" example

[adamnfish]

At the moment, the "Get started" button on the homepage links to the Installation documentation, but doesn't include instructions on setting Scalafmt up for a project. I have observed that this creates significant friction for engineers that are new to Scala.

It's tough to discover that there are two required pieces of configuration, and what the values of these should be. Even on the configuration page (which addresses more complex examples) there's no clear of example of a minimal working config definition that teams can start from. This means Scalafmt is only accessible to engineers that already know how it works, or that have somewhere else to copy a working config file from.

This change adds a note to the top of the Installation documentation, because:

1. this page is linked from "Get started" so it is the first thing people see
2. It's reasonable to interpret "Installing" to mean setting up Scalafmt on the project

We use the @STABLE_VERSION@ reference so that these docs will always point to the correct version of Scalafmt. This is especially important because there are two different versions of Scalafmt (scalafmt-core / sbt-scalafmt), which is a detail that someone just setting up IDE formatting won't need to understand.

I think this proposal addresses the 99% use case of someone just wanting sensible auto-formatting in their IDE and needing to fill in the required pieces of configuration without any customisation. I'm open to the idea that something like this could go on the homepage (at https://scalameta.org/scalafmt/) instead and of course, if this isn't aligned with the documentation's goals then let's chat about that instead 🙏

[kitbellew]

thank you, it's a good suggestion.

[kitbellew]

1. move this to the very first example in the configuration page
2. mark each of these two lines there with a # mandatory comment
3. use scala213; if we are talking about complete newbies, using scala3 for 2.13 is likely to lead to very unhappy outcomes.

[kitbellew]

replace this section with a simple

## Configuration

head and below it a link to the configuration page, possibly with a short note stressing importance of this step.

[adamnfish]

@kitbellew Thank you for the great suggestions. I've changed the PR to reflect these (and will flatten the history once we've got to a happy point).

As prompted, we now have a working example at the top of the Configuration documentation, linked from the top of the Installation page.

One important note is that I've removed the maxColumn = 1234 config directive here, so that we have a real working example as a reference. My suspicion is that this reference configuration will be used by a lot of engineers so I'd be interested to hear whether you think we should keep the align.preset = more directive as well, since it doesn't align with the default value.

[kitbellew]

please put it back, it was the subject of a very long debate. if you absolutely must -- although we thought it obvious -- you could add a comment asking user to substitute a real, less fantastic value.

[adamnfish]

I understand that these things are complicated, so for sure I'll put it back now 🙏

I want to stress though that my goal here is to document how to use Scalafmt for someone that doesn't already know, something that previously took a careful read of the documentation. One reason I had originally used a separate location for this example was to document the minimal requirements without needing to get into the weeds. The tendency to cater exclusively to the advanced use case is a common problem in Scala tooling, and I constantly see the negative impact it has on developers new to Scala. While I still think this PR helps as-is, the fact that this introductury example is an invalid configuration is a shame!

Perhaps an alternative would be to add a section above the most popular heading that documents the two required fields. The challenge with this (and why I didn't start with this approach) is that it would mean separating the (mandatory) dialect documenation from the (optional) dialectOverride setting. Another approach would be to add a "quickstart" on the home page as mentioned above, or as its own separate documentation section.

I'll leave these suggestion as something for you and the team to consider after the fact though, no need to extend this PR converstion here, and thanks again for the great feedback ❤️

[kitbellew]

• i purposely don't want to mention configuration anywhere else
  • people don't read this page and [ab]use discord for help with stuff they could have read here
  • perhaps one of the recent llms might help with that, though, i haven't tried
• take a look at git blame for the maxColumn line, and should be able to find a heated discussion regarding standards, style guides etc.
  • there's no such thing as a canonical scalafmt configuration, yet this example here is invariably taken as that, with the upheaval that it brings.
  • so, 1234 was chosen as a pretty obvious stupid number, so people will quickly realize they need to change it, and the choice is not that hard

feel free to separate the two new mandatory lines from the others with a // here are some examples of optional settings comment.

[adamnfish]

I've squashed this to the resulting diff, and updated this branch from main.

[kitbellew]

let me know if you'd like to add a clarifying comment, or you're done.

[kitbellew]

• i purposely don't want to mention configuration anywhere else
  • people don't read this page and [ab]use discord for help with stuff they could have read here
  • perhaps one of the recent llms might help with that, though, i haven't tried
• take a look at git blame for the maxColumn line, and should be able to find a heated discussion regarding standards, style guides etc.
  • there's no such thing as a canonical scalafmt configuration, yet this example here is invariably taken as that, with the upheaval that it brings.
  • so, 1234 was chosen as a pretty obvious stupid number, so people will quickly realize they need to change it, and the choice is not that hard

feel free to separate the two new mandatory lines from the others with a // here are some examples of optional settings comment.

[adamnfish]

I've added your suggested comment, I do think this helps!

Let me know if this looks ok, and thanks again for all your attention here 🙏