One manual in place of twenty-six pages - #359
Open
wenjing wants to merge 1 commit into
Open
Conversation
The documentation was 26 pages and about 3,400 lines with no owner and heavy overlap — five of them were about benchmarking. Nobody read the set as a whole, which is how a walkthrough came to show a captured session naming intermediaries that no longer existed, inside an encoded message that could not be corrected by hand. The failure was not that pages were wrong. Correctness cannot be maintained across twenty-six overlapping documents, so it was not. The remedy is less documentation rather than better-organised documentation: document what has to be true and let the specification and the generated API documentation carry the rest. One document now, in four parts: using the protocol from the command line, embedding the library, operating the services, and working on the SDK. Operating the services had no page at all before, and it is where the failures of the past days would have been prevented. mdBook goes with it, along with its configuration and the workflow that installed it and a mermaid preprocessor that was never checked in. Twenty anchor comments in the Rust and Python sources existed only to feed its include directives and are removed too. Three design records that were never part of the book are kept: the buffer protocol design, the survey of how other systems buffer messages, and the transport design that was implemented from it. Signed-off-by: Wenjing Chu <chu.wenjing@gmail.com>
|
Bencher Report| Project | tsp project |
| Branch | pr-359 |
| Testbed | ubuntu-latest |
⚠️ WARNING: Truncated view!The full continuous benchmarking report exceeds the maximum length allowed on this platform.
🐰 View full continuous benchmarking report in Bencher
⚠️ WARNING: No Threshold found!Without a Threshold, no Alerts will ever be generated.
|
| Project | tsp project |
| Branch | pr-359 |
| Testbed | ubuntu-latest |
⚠️ WARNING: No Threshold found!Without a Threshold, no Alerts will ever be generated.
- Instructions (instructions)
- Estimated Cycles (cycles)
- LL Hits (hits)
- RAM Hits (hits)
- Total read+write (reads/writes)
- L1 Hits (hits)
Click here to create a new Threshold
For more information, see the Threshold documentation.
To only post results if a Threshold exists, set the--ci-only-thresholdsflag.
Click to view all benchmark results
| Benchmark | Estimated Cycles | cycles x 1e6 | Instructions | instructions x 1e6 | L1 Hits | hits x 1e6 | LL Hits | hits x 1e3 | RAM Hits | hits x 1e3 | Total read+write | reads/writes x 1e6 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| guardrail_pq::guardrail_pq::guardrail_crypto_seal_open_hpke_pq direct_0b:setup_seal_open("guardrail.crypto.seal_open.hpke_pq.direct.0B", 0) | 📈 view plot | 14.85 x 1e6 | 📈 view plot | 10.94 x 1e6 | 📈 view plot | 14.63 x 1e6 | 📈 view plot | 29.37 x 1e3 | 📈 view plot | 2.27 x 1e3 | 📈 view plot | 14.66 x 1e6 |
| guardrail_pq::guardrail_pq::guardrail_crypto_seal_open_hpke_pq direct_16kib:setup_seal_open("guardrail.crypto.seal_open.hpke_pq.direct.16KiB", 16 * 1024) | 📈 view plot | 25.97 x 1e6 | 📈 view plot | 19.88 x 1e6 | 📈 view plot | 25.61 x 1e6 | 📈 view plot | 56.08 x 1e3 | 📈 view plot | 2.34 x 1e3 | 📈 view plot | 25.67 x 1e6 |
| guardrail_pq::guardrail_pq::guardrail_crypto_seal_open_hpke_pq direct_1kib:setup_seal_open("guardrail.crypto.seal_open.hpke_pq.direct.1KiB", 1024) | 📈 view plot | 17.78 x 1e6 | 📈 view plot | 13.38 x 1e6 | 📈 view plot | 17.51 x 1e6 | 📈 view plot | 36.94 x 1e3 | 📈 view plot | 2.30 x 1e3 | 📈 view plot | 17.55 x 1e6 |
| guardrail_pq::guardrail_pq::guardrail_crypto_sign_verify_mldsa65 direct_0b:setup_sign_verify("guardrail.crypto.sign_verify.mldsa65.direct.0B", 0) | 📈 view plot | 9.09 x 1e6 | 📈 view plot | 6.85 x 1e6 | 📈 view plot | 8.92 x 1e6 | 📈 view plot | 26.23 x 1e3 | 📈 view plot | 1.10 x 1e3 | 📈 view plot | 8.95 x 1e6 |
| guardrail_pq::guardrail_pq::guardrail_crypto_sign_verify_mldsa65 direct_16kib:setup_sign_verify("guardrail.crypto.sign_verify.mldsa65.direct.16KiB", 16 * 1024) | 📈 view plot | 15.51 x 1e6 | 📈 view plot | 11.95 x 1e6 | 📈 view plot | 15.27 x 1e6 | 📈 view plot | 39.42 x 1e3 | 📈 view plot | 1.23 x 1e3 | 📈 view plot | 15.31 x 1e6 |
| guardrail_pq::guardrail_pq::guardrail_crypto_sign_verify_mldsa65 direct_1kib:setup_sign_verify("guardrail.crypto.sign_verify.mldsa65.direct.1KiB", 1024) | 📈 view plot | 7.83 x 1e6 | 📈 view plot | 5.77 x 1e6 | 📈 view plot | 7.68 x 1e6 | 📈 view plot | 22.64 x 1e3 | 📈 view plot | 1.10 x 1e3 | 📈 view plot | 7.70 x 1e6 |
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.
26 pages, about 3,400 lines, no owner, heavy overlap — five of them about benchmarking. Nobody
read the set as a whole, which is how a walkthrough came to show a captured session naming
intermediaries that no longer existed, inside an encoded message that could not be corrected by
hand.
The failure was not that individual pages were wrong. Correctness cannot be maintained across
twenty-six overlapping documents, so it was not maintained. The remedy is less documentation
rather than better-organised documentation: write down what has to be true, and let the
specification and the generated API documentation carry the rest.
What replaces it
docs/manual.md, 304 lines, four parts:intermediaries, nesting. Absorbs all five CLI pages.
and storage. Points at docs.rs rather than restating the API.
intermediary's identity must persist, and why its wallet is a single object rather than a
mounted filesystem. This had no page at all, and it is where the failures of the past days
would have been prevented.
of them. Benchmarking is one section rather than five pages.
Also removed
mdBook, its configuration, and the workflow installing it and a mermaid preprocessor that was
never checked in — it already broke the docs build locally. Twenty anchor comments in the Rust and
Python sources existed only to feed its include directives, which do not render on GitHub anyway.
Kept
Three design records that were never part of the book: the buffer protocol design, the survey of
how other systems buffer messages, and the transport design implemented from it. Those are
records of thinking rather than user documentation.
Not addressed here
docs.teaspoon.worldstill needs retiring; nothing in the repository points at it any more.