Send the reader to the page that argues it, once - #89
Merged
Conversation
Three of the nine Usage subsections were saying what a documentation page already says, and saying it worse for being shorter. Reading a failure is errors.md, which carries the whole argument for why drift is a measurement rather than an exception. On a hot path is the Run section of benchmarks.md, down to the same four-to-seven microseconds and the same conclusion about which models it is worth reaching for on. Every backend at once is where the numbers come from in backend-coverage.md, which reports the per-backend bounds rather than eliding them into one example. The README also printed a failing parity report three times: once in the pitch, once under the gate, once under Reading a failure. Once is the demonstration. backend-coverage.md was reachable from no link in the README, so cutting the section that stood in for it needed the page added to the documentation list first. The six remaining subsections stay because nothing else covers them: generated preprocessing, reported capabilities, and an artifact whose weights live outside its graph appear on no page of the site.
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.
## Usagewas 196 of the README's 440 lines. Three of its nine subsections wererepeating a documentation page, and the page was the better of the two in every
case.
errors.md, which carries the full argument for why drift is a measurement and not an exceptionbenchmarks.md, same four-to-seven microseconds, same conclusion, plus the tablebackend-coverage.md, which reports each backend's own bound instead of one example rowThe README was also printing a failing parity report three times over: in the
pitch, under the gate, and again under Reading a failure. Once is the
demonstration; the third makes the first look padded.
What did not get cut, and why
Six subsections stay. Generated preprocessing (
fromSource, the resize and thecentre crop), reported capabilities (
supportsActivationTaps,supportsDeterministicExecution) and multi-part artifacts(
parts,BundlePartMissingException) appear on no page of the site. Cuttingthose would not remove a duplicate, it would remove the only copy. They are
candidates for pages of their own, which is a separate change.
One link that had to be added first
backend-coverage.mdwas reachable from nowhere in the README. Removing thesection that stood in for it without adding the page to the documentation list
would have made the page unreachable rather than the section redundant.
374 lines, from 440. Every documentation link in the file was checked to
resolve to a page that exists.