Improving the bundle config (1) man page and web page

[dogweather]

User Story

As an application developer, I want to run bundle install in CI, skipping installation of production and development groups.

I know that the existing way things were done (bundle install --without ...) is deprecated, so I need to learn the new syntax.

What I expected

Docs on the website that I could read/browse within a minute or two, to just learn the new syntax.

What I saw

• A notice on the install page, advising to use config.
• A notice on the config page, advising to use install or cache for per-app settings (which is what the deprecated syntax does, if I'm right.)
• Descriptions of without syntax on config that seem to conflict with each other.
• Extremely long text with many sections.

I couldn't figure out how the sections are related. I ended up just installing everything with bundle install because of the doc sections that seemed to conflict.

What I propose

I think this page could use a lot of help. I'd like to start a series of small PRs with gradual improvements.

For starters, I'd fix—or clarify—the without syntax. Currently, the page has this in one spot:

without (BUNDLE_WITHOUT): A :-separated list of groups…

and this in another:

without A space-separated list of groups…

Next, I'd add an Examples section containing the common use case in my user story. I have more ideas.

Thanks! Just checking if a PR would be welcomed.

[deivid-rodriguez]

Thank you. Yes, documentation improvements are always welcome!

First thing I'd fix is any contradictory information, and then I'd focus on other improvements. Can you point out where you saw the following?

A notice on the config page, advising to use install or cache for per-app settings (which is what the deprecated syntax does, if I'm right.)

[dogweather]

Can you point out where you saw the following?

Sure: https://bundler.io/v2.5/man/bundle-config.1.html

[deivid-rodriguez]

Good catch! Yes, we should definitely be changing that, and a PR will be highly appreciated!

[dogweather]

Great. Do you know offhand how it should read? I found that bundle config sets a user's global configuration. Is there a per-app option that can be a drop-in replacement for the deprecated usage?

[deivid-rodriguez]

Actually, bundle config already sets per-app configuration. Per user would be bundle config --global. We changed bundle config to use --local by default a while ago. If you found docs saying that bundle config is per-user, you may have found another documentation bug! 😅

Regarding how this should read, I'm thinking, should we remove these two paragraphs altogether? Configuration precedence is already explained at the top of the page, so maybe not needed here?