docs: overhauled docs (#895)

## PR Checklist

- [x] Addresses an existing open issue: fixes #856
- [x] That issue was marked as [`status: accepting
prs`](https://github.com/JoshuaKGoldberg/create-typescript-app/issues?q=is%3Aopen+is%3Aissue+label%3A%22status%3A+accepting+prs%22)
- [x] Steps in
[CONTRIBUTING.md](https://github.com/JoshuaKGoldberg/create-typescript-app/blob/main/.github/CONTRIBUTING.md)
were taken

## Overview

Streamlines the flow of how devs will likely read through the docs. Most
notably, adds a big `docs/Tooling.md` with a table explicitly describing
what all the tooling pieces are.

Author: JoshuaKGoldberg

.github/CONTRIBUTING.md

@@ -32,14 +32,14 @@ We don't use any kind of issue claiming system.
 We've found in the past that they result in accidental ["licked cookie"](https://devblogs.microsoft.com/oldnewthing/20091201-00/?p=15843) situations where contributors claim an issue but run out of time or energy trying before sending a PR.
 
 If an issue has been marked as `accepting prs` and an open PR does not exist, feel free to send a PR.
-You don't need to ask for permission.
+Please don't post comments asking for permission or stating you will work on an issue.
 
 ### Sending a Pull Request
 
 Once you've identified an open issue accepting PRs that doesn't yet have a PR sent, you're free to send a pull request.
 Be sure to fill out the pull request template's requested information -- otherwise your PR will likely be closed.
 
-PRs are also expected to have a title that adheres to [commitlint](https://github.com/conventional-changelog/commitlint).
+PRs are also expected to have a title that adheres to [conventional commits](https://www.conventionalcommits.org/en/v1.0.0).
 Only PR titles need to be in that format, not individual commits.
 Don't worry if you get this wrong: you can always change the PR title after sending it.
 Check [previously merged PRs](https://github.com/JoshuaKGoldberg/create-typescript-app/pulls?q=is%3Apr+is%3Amerged+-label%3Adependencies+) for reference.

.github/DEVELOPMENT.md

@@ -121,9 +121,12 @@ pnpm run test:create
 
 That end-to-end test executes `script/create-test-e2e.js`, which:
 
-1. Runs the creation script to create a new `test-repository` child directory and repository
+1. Runs the creation script to create a new `test-repository` child directory and repository, capturing code coverage
 2. Asserts that commands such as `build` and `lint` each pass
 
+The `pnpm run test:create` script is run in CI to ensure that templating changes are in sync with the template's actual files.
+See `.github/workflows/test-create.yml`.
+
 ### The Initialization Script
 
 This template's "initialization" script is located in `src/initialize/`.
@@ -134,8 +137,6 @@ It uses [`tsx`](https://github.com/esbuild-kit/tsx) so you don't need to build f
 pnpm run initialize
 ```
 
-> 💡 Consider running `git add -A` to stage all local changes before running.
-
 #### Testing the Initialization Script
 
 You can run the end-to-end test for initializing locally on the command-line.
@@ -188,7 +189,7 @@ pnpm run test:migrate
 
 That end-to-end test executes `script/migrate-test-e2e.js`, which:
 
-1. Runs the migration script using `--skip-github-api` and other skip flags
+1. Runs the migration script using `--skip-github-api` and other skip flags, capturing code coverage
 2. Checks that only a small list of allowed files were changed
 3. Checks that the local repository's files were changed correctly (e.g. removed initialization-only files)
 

README.md

@@ -1,6 +1,6 @@
 <h1 align="center">Create TypeScript App</h1>
 
-<p align="center">Quickstart-friendly TypeScript template with comprehensive formatting, linting, releases, testing, and other great tooling built-in. ✨</p>
+<p align="center">Quickstart-friendly TypeScript template with comprehensive, configurable, opinionated tooling. 💝</p>
 
 <p align="center">
 	<a href="#contributors" target="_blank">
@@ -29,6 +29,9 @@
 
 <img align="right" alt="Project logo: the TypeScript blue square with rounded corners, but a plus sign instead of 'TS'" src="./create-typescript-app.png">
 
+`create-typescript-app` is a one-stop-shop solution to set up a new or existing repository with the latest and greatest TypeScript tooling.
+It includes options not just for building and testing but also GitHub repository templates, contributor recognition, automated release management, and more.
+
 ## Getting Started
 
 First make sure you have the following installed:
@@ -37,36 +40,31 @@ First make sure you have the following installed:
 - [Node.js](https://nodejs.org)
 - [pnpm](https://pnpm.io)
 
-This repository comes with three script forms to set up an existing or new repository with tooling.
-Use the corresponding docs page to get started:
+Then in an existing repository or in your directory where you'd like to make a new repository:
+
+```shell
+npx create-typescript-app
+```
 
-- [Creating from the terminal](./docs/Creation.md): creating a new repository locally on the command-line _(recommended)_
-- [Initializing from the template](./docs/Initialization.md): creating a new repository with the [_Use this template_](https://github.com/JoshuaKGoldberg/create-typescript-app/generate) button on GitHub
-- [Migrating an existing repository](./docs/Migration.md): adding this template's tooling on top of an existing repository
+That setup script will walk you through using the template.
+You can read more about the supported setup modes in their docs pages:
 
-Note that this template is early stage, opinionated, and not endorsed by the TypeScript team.
-It can be configured to set up a _lot_ of tooling out of the box.
-Each of the included tools exists for a good reason and provides real value.
+- [**Creating from the terminal**](./docs/Creation.md): creating a new repository locally on the command-line _(recommended)_
+- [**Initializing from the template**](./docs/Initialization.md): creating a new repository with the [_Use this template_](https://github.com/JoshuaKGoldberg/create-typescript-app/generate) button on GitHub
+- [**Migrating an existing repository**](./docs/Migration.md): adding this template's tooling on top of an existing repository
 
-If you don't want to use any particular tool, you can always remove it manually.
+## Documentation
 
-## Explainer
+You can read more about `create-typescript-app` and the tooling it supports:
 
-This template is available for anybody who wants to set up a Node application using TypeScript.
-It can set up the following tooling for you:
+1. [**Tooling**](./docs/Tooling.md): a breakdown of all the pieces this template can set up.
+2. [**Options**](./docs/Options.md): granular options to customize how the template is run.
+3. [**FAQs**](./docs/FAQs.md): frequently asked questions
 
-- [**All Contributors**](https://allcontributors.org): Tracks various kinds of contributions and displays them in a nicely formatted table in the README.md.
-- [**ESLint**](https://eslint.org): Static analysis for JavaScript code, configured with [typescript-eslint](https://typescript-eslint.io) for TypeScript code and other general-use plugins.
-- [**Knip**](https://github.com/webpro/knip): Detects unused files, dependencies, and code exports.
-- [**Markdownlint**](https://github.com/DavidAnson/markdownlint): Static analysis for Markdown code.
-- [**pnpm**](https://pnpm.io): Disk-efficient package manager alternative.
-- [**PR Compliance Action**](https://github.com/mtfoley/pr-compliance-action): Checks PRs for compliance such as addressing a linked issue and proper title formatting.
-- [**Prettier**](https://prettier.io): Opinionated formatting for code, run on file save and as a Git commit hook via [husky](https://typicode.github.io/husky) and [lint-staged](https://github.com/okonet/lint-staged).
-- [**release-it**](https://github.com/release-it/release-it): Generates changelogs, bumps the package version, and publishes to GitHub and npm based on [conventional commits](https://www.conventionalcommits.org).
-- [**Renovate**](https://docs.renovatebot.com): Keeps dependencies up-to-date with PRs, configured to wait a few days after each update for safety.
-- [**tsup**](https://tsup.egoist.dev): Builds output definitions and JavaScript files using [esbuild](https://esbuild.github.io).
-- [**TypeScript**](https://typescriptlang.org): A typed superset of JavaScript, configured with strict compiler options.
-- [**Vitest**](https://vitest.dev): Fast unit tests, configured with coverage tracking and [console-fail-test](https://github.com/JoshuaKGoldberg/console-fail-test).
+> [!NOTE]  
+> This template is early stage, opinionated, and not endorsed by the TypeScript team.
+> It can be configured to set up a _lot_ of tooling out of the box.
+> If you don't want to use any particular tool, you can always remove it manually.
 
 ## Development
 

docs/Creation.md

@@ -1,6 +1,6 @@
 # Creating from the Terminal
 
-You can run `npx create-typescript-app` in your terminal to interactively create a new repository:
+You can run `npx create-typescript-app` in your terminal to interactively create a new repository in a child directory:
 
 ```shell
 npx create-typescript-app
@@ -28,3 +28,5 @@ For example, running the creation script and skipping all GitHub APIs:
 ```shell
 npx create-typescript-app --mode create --skip-all-contributors-api --skip-github-api
 ```
+
+See [Tooling.md](./Tooling.md) for details on the tooling pieces and which bases they're included in.

docs/FAQs.md

@@ -9,25 +9,24 @@ If you think the tool would be broadly useful to most consumers of this template
 
 ## Is there a way to pull in template updates to previously created repositories?
 
-Not yet.
-You can always copy & paste them in manually.
+Not directly.
+You can always copy & paste them in manually, and/or re-run `npx create-typescript-app --mode migrate`.
 
 See [🚀 Feature: Add a script to sync the tooling updates from forked template repo #498](https://github.com/JoshuaKGoldberg/create-typescript-app/issues/498): it will likely eventually be possible.
 
-## Why does this package include so many tools?
-
-This repository is meant to serve as a starter that includes all the general tooling a modern TypeScript/Node repository could possibly need.
-Each of the included tools exists for a good reason and provides real value.
+### What about `eslint-config-prettier`?
 
-If you don't want to use any particular tool, you can always remove it manually.
+[`eslint-config-prettier`](https://github.com/prettier/eslint-config-prettier) is an ESLint plugin that serves only to turn off all rules that are unnecessary or might conflict with formatters such as Prettier.
+None of the ESLint configs enabled by this repository's tooling leave any rules enabled that would need to be disabled.
+Using `eslint-config-prettier` would be redundant.
 
 ### What determines which "base" a tool goes into?
 
 The four bases correspond to what have seemed to be the most common user needs of template consumers:
 
 1. **Minimum**: Developers who just want the barest of starting templates.
    - They may be very new to TypeScript tooling, or they may have made an informed decision that the additional tooling isn't worth the complexity and/or time investment.
-   - Tooling in this base is only what would be essential for a small TypeScript package that can be built, formatted, and linted.
+   - Tooling in this base is only what would be essential for a small TypeScript package that can be built, formatted, linted, and released.
 2. **Common**: The common case of users who want the minimum tooling along with common repository management.
    - Tooling added in this base should be essential for a TypeScript repository that additionally automates useful GitHub tasks: contributor recognition, release management, and testing.
 3. **Everything**: Power users (including this repository) who want as much of the latest and greatest safety checks and standardization as possible.
@@ -45,3 +44,10 @@ The following pieces of this template's tooling don't have options to be removed
 - TypeScript and `pnpm run tsc`
 
 If you have a strong desire to add an `--exclude-*` flag for any of them, please do [file a feature request](https://github.com/JoshuaKGoldberg/create-typescript-app/issues/new?assignees=&labels=type%3A+feature&projects=&template=03-feature.yml&title=%F0%9F%9A%80+Feature%3A+%3Cshort+description+of+the+feature%3E).
+
+## Why does this package include so many tools?
+
+This repository is meant to serve as a starter that includes all the general tooling a modern TypeScript/Node repository could possibly need.
+Each of the included tools exists for a good reason and provides real value.
+
+If you don't want to use any particular tool, you can always remove it manually.

docs/Initialization.md

@@ -42,3 +42,5 @@ For example, running the initialization script and skipping all GitHub APIs:
 ```shell
 pnpm run initialize --skip-all-contributors-api --skip-github-api
 ```
+
+See [Tooling.md](./Tooling.md) for details on the tooling pieces and which bases they're included in.

docs/Migration.md

@@ -6,7 +6,7 @@ If you have an existing repository that you'd like to give the files from this r
 npx create-typescript-app
 ```
 
-> **Warning**
+> [!WARNING]
 > Migration will override many files in your repository.
 > You'll want to review each of the changes.
 > There will almost certainly be some incorrect changes you'll need to fix.
@@ -21,3 +21,5 @@ For example, running the migration script and skipping all GitHub APIs:
 ```shell
 npx create-typescript-app --mode migrate --skip-all-contributors-api --skip-github-api
 ```
+
+See [Tooling.md](./Tooling.md) for details on the tooling pieces and which bases they're included in.

docs/Options.md

@@ -2,7 +2,7 @@
 
 All three of `create-typescript-app`'s setup scripts -[creation](./Creation.md), [initialization](./Initialization.md), and [migration](./Migration.md)- support a shared set of input options.
 
-> This page uses `npx create-typescript-app` in its code examples, but `pnpm run initialize` works the same.
+> This page uses `npx create-typescript-app` in its code examples, but initialization's `pnpm run initialize` works the same.
 
 ## Required Options
 
@@ -13,21 +13,24 @@ The following required options will be prompted for interactively if not provide
 These required options determine how the creation script will set up and scaffold the repository:
 
 - `--base`: Whether to scaffold the repository with:
-  - `everything` that comes with the template _(recommended)_
-  - `minimum` amounts of tooling, essentially opting out of everything
-  - `prompt` for which portions to exclude
+  - `minimum`: Just the bare starter tooling most repositories should ideally include.
+  - `common`: Important additions to the minimum starters such as releases and tests.
+  - `everything`: The most thorough tooling imaginable: sorting, spellchecking, and more!
+  - `prompt`: Fine-grained control over which tooling pieces to use
 - `--create-repository` _(boolean)_: Whether to create a corresponding repository on github.com (if it doesn't yet exist)
 - `--mode`: Whether to:
   - `create` a new repository in a child directory
   - `initialize` a freshly repository in the current directory
   - `migrate` an existing repository in the current directory
 
-For example, scaffolding a full new repository in the current directory and also linking it to a new repository on github.com:
+For example, scaffolding a full new repository under the current directory and also linking it to a new repository on github.com:
 
 ```shell
 npx create-typescript-app --base everything --create-repository --mode create
 ```
 
+See [Tooling.md](./Tooling.md) for details on the tooling pieces and which bases they're included in.
+
 ### Core Options
 
 These required options determine the options that will be substituted into the template's files:
@@ -49,7 +52,7 @@ That script will run completely autonomously, no prompted inputs required. ✨
 
 The setup scripts also allow for optional overrides of the following inputs whose defaults are based on other options:
 
-- `--access` _(`"public" | "restricted`)_: Which [`npm publish --access`](https://docs.npmjs.com/cli/commands/npm-publish#access) to release npm packages with (by default, `"public"`)
+- `--access` _(`"public" | "restricted"`)_: Which [`npm publish --access`](https://docs.npmjs.com/cli/commands/npm-publish#access) to release npm packages with (by default, `"public"`)
 - `--author` _(`string`)_: Username on npm to publish packages under (by default, an existing npm author, or the currently logged in npm user, or `owner.toLowerCase()`)
 - `--email` _(`string`)_: Email address to be listed as the point of contact in docs and packages (e.g. `[email protected]`)
   - Optionally, `--email-github` _(`string`)_ and/or `--email-npm` _(`string`)_ may be provided to use different emails in `.md` files and `package.json`, respectively
@@ -105,6 +108,8 @@ npx create-typescript-app --exclude-lint-package-json --exclude-lint-packages --
 > **Warning**
 > Specifying any `--exclude-*` flag on the command-line will cause the setup script to skip prompting for more excludes.
 
+See [Tooling.md](./Tooling.md) for details on the tooling pieces and which bases they're included in.
+
 ### Skipping API Calls
 
 > Alternately, see [Offline Mode](#offline-mode) to skip API calls without disabling features