Skip to content

docs: comprehensive review across all user-facing documentation#61

Merged
bigin merged 1 commit into
mainfrom
docs/comprehensive-review
May 17, 2026
Merged

docs: comprehensive review across all user-facing documentation#61
bigin merged 1 commit into
mainfrom
docs/comprehensive-review

Conversation

@bigin

@bigin bigin commented May 17, 2026

Copy link
Copy Markdown
Owner

Audits 18 files: README, CHANGELOG, every tutorial chapter, every API reference page, the field-types and query cookbooks, the deployment guide, and the 1.x to 2.0 migration guide.

Content corrections (each verified against source):

  • storage.md: generated-column SQL example now gen_<catId>_<field>
    • VIRTUAL (was field_<name> + STORED); migration table updated to .sql extensions and to include 0005_searchable_defaults.
  • api/field-types.md: InputErrorCode::PatternMismatch in the custom-plugin sketch replaced with WrongValueFormat (the invented case was supposed to have been removed in 2.0.0). defaultConfig() table rewritten against the actual plugin sources: all 16 built-ins now listed with their real keys and defaults. New callout explains the documented divergence between fluent-setter keys (maxBytes, mimes, format) and the upload plugins' runtime keys (maxSizeBytes, acceptedExtensions).
  • domain.md: config examples switched to plugin-read keys (maxLength, acceptedExtensions) instead of stale max / mimes.
  • tutorial/files.md: FileStorage is a seven-method interface (text incorrectly said five); thumbnail code-block typo $thumbThumbPath resolved by inlining $thumbRelative.
  • query-cookbook.md: EXPLAIN QUERY PLAN example now uses gen_7_active (matching the actual generated-column naming); migration-format link bumped to 0001-0005.
  • migration-guide.md: composer constraint bumped from the stale 2.0.x-dev to ^2.0; --database flag corrected to --db; schema-status output and prose reflect five migrations (was four).
  • README + tutorial/README + tutorial/setup + api/README + cookbook: version reference bumped from 2.0 / 2.0.2 to 2.2.1 (or "iManager 2" where the line is what matters); README CLI table optimize row clarified (--vacuum is opt-in, not always run).

Independence cleanup (the project rule that iManager docs never name their consumers had drifted in a few places):

  • CHANGELOG 2.2.0/2.2.1: removed downstream-consumer naming and the specific schema field list.
  • tutorial/setup.md: removed the "Scriptor's frontend" example for the cache path.
  • tutorial/schema.md: removed the Scriptor-specific perf-smoke paragraph and swapped "scriptor" as an example search term for "introduction".
  • tutorial/search.md: removed the same Scriptor perf-smoke paragraph (left "scriptor" as an example search term per request).

Style pass: roughly 250 em-dashes used as connectors replaced with periods, colons, commas, or rewritten sentences across the corpus. Heading-style em-dashes (## Step 1 - ...), Keep-a-Changelog version headers (## [2.2.1] - 2026-05-17), legitimate two-dash parenthetical pairs, and verbatim CLI output are preserved.

No code changes; no public API changes.

Audits 18 files: README, CHANGELOG, every tutorial chapter, every
API reference page, the field-types and query cookbooks, the
deployment guide, and the 1.x to 2.0 migration guide.

Content corrections (each verified against source):

- storage.md: generated-column SQL example now `gen_<catId>_<field>`
  + `VIRTUAL` (was `field_<name>` + `STORED`); migration table updated
  to `.sql` extensions and to include `0005_searchable_defaults`.
- api/field-types.md: `InputErrorCode::PatternMismatch` in the
  custom-plugin sketch replaced with `WrongValueFormat` (the invented
  case was supposed to have been removed in 2.0.0). `defaultConfig()`
  table rewritten against the actual plugin sources: all 16 built-ins
  now listed with their real keys and defaults. New callout explains
  the documented divergence between fluent-setter keys (`maxBytes`,
  `mimes`, `format`) and the upload plugins' runtime keys
  (`maxSizeBytes`, `acceptedExtensions`).
- domain.md: `config` examples switched to plugin-read keys
  (`maxLength`, `acceptedExtensions`) instead of stale `max` / `mimes`.
- tutorial/files.md: `FileStorage` is a seven-method interface (text
  incorrectly said five); thumbnail code-block typo `$thumbThumbPath`
  resolved by inlining `$thumbRelative`.
- query-cookbook.md: `EXPLAIN QUERY PLAN` example now uses
  `gen_7_active` (matching the actual generated-column naming);
  migration-format link bumped to `0001`-`0005`.
- migration-guide.md: composer constraint bumped from the stale
  `2.0.x-dev` to `^2.0`; `--database` flag corrected to `--db`;
  schema-status output and prose reflect five migrations (was four).
- README + tutorial/README + tutorial/setup + api/README + cookbook:
  version reference bumped from `2.0` / `2.0.2` to `2.2.1` (or
  "iManager 2" where the line is what matters); README CLI table
  `optimize` row clarified (`--vacuum` is opt-in, not always run).

Independence cleanup (the project rule that iManager docs never name
their consumers had drifted in a few places):

- CHANGELOG 2.2.0/2.2.1: removed downstream-consumer naming and the
  specific schema field list.
- tutorial/setup.md: removed the "Scriptor's frontend" example for
  the cache path.
- tutorial/schema.md: removed the Scriptor-specific perf-smoke
  paragraph and swapped "scriptor" as an example search term for
  "introduction".
- tutorial/search.md: removed the same Scriptor perf-smoke paragraph
  (left "scriptor" as an example search term per request).

Style pass: roughly 250 em-dashes used as connectors replaced with
periods, colons, commas, or rewritten sentences across the corpus.
Heading-style em-dashes (`## Step 1 - ...`), Keep-a-Changelog version
headers (`## [2.2.1] - 2026-05-17`), legitimate two-dash parenthetical
pairs, and verbatim CLI output are preserved.

No code changes; no public API changes.
@bigin bigin merged commit 05b51a0 into main May 17, 2026
2 checks passed
@bigin bigin deleted the docs/comprehensive-review branch May 17, 2026 11:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant