18: Write the docs for the developer integrating this library - #32
Open
nikolaystrikhar wants to merge 1 commit into
Open
18: Write the docs for the developer integrating this library#32nikolaystrikhar wants to merge 1 commit into
nikolaystrikhar wants to merge 1 commit into
Conversation
Every doc but one now describes behaviour rather than the class that performs it. A host reading about the redirect does not need to know a Redirector decided it, and naming the class taught them a name they cannot use for anything: it is bound by class name, so the only thing they could do with it is rebind it, which is a separate subject. That subject is now docs/extending.md, the one file allowed to name internals -- the interface seams, the after-boot rule for class-name bindings, the four notice objects, and remove_filter() on the two named admin callbacks. It is assembled from paragraphs that were scattered across the ends of three other files, where a reader who did not want to replace anything had to scroll past them. Two sections moved to where a reader looks for them rather than where they were first written. The load-gate diagram was illustrating the enabled key in a recipe; it is the load path, so it is configuration.md's "How a sub-plugin loads", and the recipe links to it. Activation rationale that recipes.md and configuration.md each carried a version of is now stated once, in configuration.md, with the multisite loop left as the recipe it is. The rest is cut. What went is maintainer justification -- the alternatives weighed, the ordering arguments, the paragraph on why a notice queue is an option and not a transient -- which belongs in CLAUDE.md, next to the code it constrains, and reads to a host as reasons to doubt a decision they are not being asked to make. Every warning that changes what a host writes stays, down to the should_load polarity trap.
nikolaystrikhar
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What: rewrites README.md and every file in docs/ for a host developer rather than a maintainer, adds docs/extending.md, and moves the load-gate diagram to configuration.md and the activation rationale out of recipes.md.
Usage: read them on this branch —
README ·
Installing ·
Configuration ·
Recipes ·
Conflict handling ·
Filters ·
Notices ·
Extending
Why this way:
Every doc but one describes behaviour, not the class that performs it. Naming the class that decides the redirect taught a host a name they cannot use: it is bound by class name, so the only thing to do with it is rebind it — a separate subject, for a different reader.
That subject is
docs/extending.md. The interface seams, the after-boot rule for class-name bindings, the four notice objects andremove_filter()on the two named admin callbacks, assembled from paragraphs that trailed the ends of three other files where everyone else had to scroll past them.Two sections moved to where a reader looks for them. The load-gate diagram was illustrating the
enabledkey inside a recipe; it is the load path, so it is configuration's. Activation rationale that two files each carried a version of is stated once, with the multisite loop left as the recipe it is.What was cut is maintainer justification. The alternatives weighed, the ordering arguments, why the notice queue is an option and not a transient — that belongs in CLAUDE.md next to the code it constrains, and reads to a host as reasons to doubt a decision they are not being asked to make. Every warning that changes what a host writes stays, down to the
should_loadpolarity trap.