Quick start guide improvements

[bradenhilton]

Is your feature request related to a problem? Please describe.

Recently, I've noticed a lot of issue/discussion activity from what I assume are mostly new users. Things like:

• Trying to manage a chezmoi config as a regular template file instead of using a config template (.chezmoi.$FORMAT.tmpl).

  • We have taken steps to prevent and discourage this, especially with chezmoi's commands, but it's still possible for someone reading the docs to assume they can just manually create dot_config/chezmoi/chezmoi.$FORMAT{.tmpl} if they haven't also seen the relevant pages on a templated config, because some of the documentation simply refers to the config file as simply {.config/chezmoi/}chezmoi.$FORMAT.

    • I am aware that it's possible to configure chezmoi without the template, but in those instances the user must directly edit .config/chezmoi/chezmoi.$FORMAT entirely outside of chezmoi. The point remains that any user who expects to manage their chezmoi config with chezmoi should use a config template.

• Rolling their own ad-hoc implementations of chezmoi features (e.g. a script that calls chezmoi execute-template for data/values instead of using a templated script), either because they don't understand the features, don't know they exist, or don't recognize how they apply to the problem they are attempting to solve.

• General issues related to things like ignoring files, such as an assumption that the .chezmoiignore file functions identically to .gitignore.

Describe the solution you'd like

When I get a bit of time, I would like to do the following:

• Potentially make the tone slightly more conversational or "blog post"-y. Think like "First, let's create a file...", "Now, let's turn the file into a template...", "Now, let's run the script" etc.

• Replace the concrete examples (e.g. .bashrc) with a self-contained "test" directory, and instead guide a new user through as many of chezmoi's features and commands as possible (or reasonable).

  • This further reduces the potential risk of someone losing any existing config files while "test-driving" chezmoi, while still teaching how to use chezmoi.

• Tackle some of chezmoi's intricacies and common incorrect assumptions with a flow like:

  1. Deliberately guide the user through making a mistake (consistent with some of the common issues we've seen)
  2. Explain why this happens
  3. Explain how to fix it

  Concrete example:

  1. Guide the user through creating two run_ scripts, but deliberately name them in a way that results in them executing in an unexpected order
  2. Explain that this happens because chezmoi runs scripts in alphabetical order
  3. Fix by naming the scripts according to our recommendations such as numbered prefixes

  This kind of contextualization should help new users understand chezmoi's "mental model".

I'm not proposing that:

• The guide be entirely rewritten from scratch. The structure and examples are already excellent, but it only walks through a limited set of features before ending with essentially "now read some more documentation".

  • This might potentially lead the user to assume that chezmoi only has limited features, or cause them to aimlessly wander through the pages hoping to find something relevant to their specific problem, which can be tricky sometimes due to how some pages are organized/nested (though this is less of an issue thanks to the generally good naming/descriptions and also the search feature).

• We attempt to cover every possible scenario in the quick start guide, but it would be beneficial to offer up to a few minimal worked examples of:

  • .chezmoi.$FORMAT.tmpl
  • .chezmoiignore
  • files
  • templates and .chezmoitemplates
  • scripts and .chezmoiscripts (then incorporate templating to build on the previous section)
  • modify_
  • possibly also things like externals and encryption

  in a single page. I believe the above will give new users enough understanding to tackle the majority of dotfile-related problems, and will hopefully explain where they need to look for something more specialized.

• This must be implemented all at once in a single PR/commit.

Of course, this has the potential downside of adding a lot of overlap and making the documentation slightly less DRY.

Describe alternatives you've considered

Maintaining the status quo.

Additional context

I understand that supporting open source software can be a largely thankless endeavour, and, on the one hand, it's reasonable to expect that anyone opening an issue/discussion has at least attempted to read the documentation, but on the other, I don't think expecting users (especially new users) to read all (or even most) of the documentation is particularly reasonable. I have been helping where I can with support, as well as using (and also contributing to) chezmoi for years now, and I'm not certain even I have read all of the documentation.

These kinds of issues/discussions can usually be resolved with a few sentences or a link to a relevant docs page, but my hope is that a slightly more proactive approach might make them less of a burden.

Obvious low effort issues where it's abundantly clear that the user has made no attempt to troubleshoot should, of course, be responded to in kind, but it's still possible for a well-intentioned user to miss something (perhaps they personally refer to something with a different term than is used in the documentation etc.).

[twpayne]

This would be fantastic, thank you.

[halostatue]

Replace the concrete examples (e.g. .bashrc) with a self-contained "test" directory, and instead guide a new user through as many of chezmoi's features and commands as possible (or reasonable).

This further reduces the potential risk of someone losing any existing config files while "test-driving" chezmoi, while still teaching how to use chezmoi.

Maybe instead of having a self-contained "test" directory, we have starter repos? chezmoi/bash-example, chezmoi/powershell-example, etc?

[bradenhilton]

Maybe instead of having a self-contained "test" directory, we have starter repos? chezmoi/bash-example, chezmoi/powershell-example, etc?

That could also work quite well, since we could preconfigure things like templates, scripts, file/directory names and attributes etc.
I think either self-contained solution is better because it teaches things like "how to/why create a templated file" rather than "how to edit .bashrc", but I do acknowledge that starting with something that users are likely to be familiar with does have its own benefits.