refactor: introduce the configure-biome guide #811
Conversation
✅ Deploy Preview for biomejs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
|
I'm wondering if the title shouldn't be "Configuring Biome" instead to be aligned with other section titles such as "Getting started". |
|
Looking at Astro: https://docs.astro.build/en/install-and-setup/ They use "Getting started", but the rest of the guides don't use the "ing" form. For example, it is "Migrate to Astro" and not "Migrating to Astro" |
|
I have no particular preferences. I was also hesitating between |
|
No strong feelings either. It just came to mind |
| while `include` is only tested on regular files. | ||
| This means that if you want to prevent Biome from traversing a folder, |
There was a problem hiding this comment.
Are you sure this is true? I used include for folders, and it worked
There was a problem hiding this comment.
I copied this from the old docs. Maybe it is badly phrased. It means to say that include doesn't prevent Biome of traversing a folder that is not covered by include.
For example, if include contains only src, Biome will still visit test.
There was a problem hiding this comment.
This should be fixed :)
Conaclos
force-pushed
the
conaclos/configure-biome-guide
branch
3 times, most recently
from
31ba50d to
e1a6188
Compare
|
Regarding title verbs, I would use the -ing forms. It appears to be the most common choice, but style guides may differ of course. “Getting Started” is the most common example, and it feels less like a command than the imperative form “Get Started”. To me, “Configure Biome” feels like an action that should be taken, like a call-to-action button. But the content of the chapter is a guide on “configuring Biome”. Found a good discussion on the topic also: https://writing.stackexchange.com/questions/1545/verb-tense-for-technical-document-titles I think the strongest argument I could find for using the imperative form (as is done currently in this PR) is that these forms of the verbs might be easier to recognize for non-English speakers. I think the strongest argument for continuous form (apart from historical convention) is that it is easiest to do consistently, since people note various examples where imperative form just feels awkward, so they still end up using “Getting Started” or the example of “Configuring Kubernetes”, despite using imperative form elsewhere). Anyway, just food for thought :) |
|
I am going to merge the PR. Please feel free to open new PRs to update translations. |
Summary
This PR renames
How Biome worksintoConfigure Biome.I tried to improve the introduction of the Configuration file by talking about its structure.
We also point to the configuration reference for users looking for that.
I introduced a new section
Ignore filesthat is the oldinclude and ignore explained, but hopefully improved.I first wanted separate this section into a dedicated guide.
However, I am no longer convinced it is a valuable change.
Also, I turn the
Protected filessection into a note inIgnore files.I merged the two sections about the
extendsfield intoShare a configuration file.I removed duplicated docs in the formatter/linter intro by pointing to the
Ignore filessection of the new guide.In the future, I think we could introduce a new section for explaining our
overridesfield.