docs: Stop the README repeating itself - #51
Merged
Merged
Conversation
The server section restated SRV-8 and SRV-12 almost claim for claim, and then restated itself: slots exempting config and probe requests appeared twice, signed subjects were recommended three times in forty lines, and sizing advice for --client-concurrency was spread across three paragraphs that wanted to be one. Seven prose blocks are now four. Signed URLs keep the worked example, the formula and the clock warning, the three operational facts a reader needs in a README. The encoding rules that only matter while debugging a signature now point at SRV-10 instead of being maintained in two places. The ten-byte probe ceiling was stated four times across two tables and two paragraphs; the tables keep it. No figures or documented limitations were dropped. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GuMYXaDafWUk2fAjyEvFDa
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.
Problem
The README's self-hosting section was 114 lines, nearly a third of the file, and most of
that weight was repetition rather than content.
It repeated itself. Config and probe requests being exempt from admission slots was
stated twice. Slots being held until the handler returns appeared twice. Signed subjects
were recommended three times in forty lines. Sizing advice for
--client-concurrencywasspread across three separate paragraphs, one of which actually opened with "Size
--client-concurrency".It also repeated the specs. The signed-URL paragraph restated SRV-10 almost claim for
claim: the HMAC formula, the leeway, the 24 hour cap, decoded paths, percent-encoded
subjects, base64 flavours, key rotation. The load-limit prose did the same to SRV-8 and
SRV-12. Two copies of one protocol, both of which have to stay correct.
docs/README.mdalready forbids this. It lists "anything already in the README" underwhen not to write a doc, and the same rule run backwards is what this section was
violating.
Solution
Seven prose blocks become four: how admission works, what the budget does not guarantee,
what a stalled request costs, and how to size the caps.
Signed URLs keep the worked example, the formula and the clock-skew warning, which are
the three things a reader needs in a README. The encoding rules that only matter while
debugging a signature now link to SRV-10 rather than being maintained in two files.
The ten-byte probe ceiling appeared four times across two tables and two paragraphs. The
tables keep it.
Net 18 lines, which is less than the repetition count suggests: removing a duplicated
claim from a wrapped paragraph usually saves a line or two, and the value here is having
one source of truth rather than a shorter file.
Other Changes
None. README.md only, no Go files touched.
I checked the diff for dropped facts by comparing the vocabulary on both sides, which
caught one real loss: the warning that a shared bearer token does not separate budgets
behind a load balancer. It is restored. Every figure, the deviations table and the
documented limitations are intact.
No screenshots: nothing rendered changed.
Related: SRV-8, SRV-10, SRV-12
🤖 Generated with Claude Code
https://claude.ai/code/session_01GuMYXaDafWUk2fAjyEvFDa