Skip to content

How this project works

My one rule

When the road in front of you is blocked, or the work turns hard, take an hour off and do something completely different. The answer shows up on its own.

It is not a technique, and it does not fit in a table. But nearly two years of this project had their share of dead ends - nineteen against one fault alone - and this is the rule I hold to whenever one appears.

The rules the work paid for

Five more came out of the work itself, each learned by paying for the alternative. They are in the road, with what each one cost.

  1. Read the vendor's own sources before probing the hardware. The adapters of chapter 4 taught it first; the port tags of chapter 9 taught it again.
  2. Write down what did not work, with the measurement. Nineteen negatives against the XGS 3300's last hop meant nineteen things nobody tried twice.
  3. Withdraw a claim in the same place it was made. Struck through, with what replaced it beside it, never deleted - a log that quietly edits itself is not a log.
  4. A number that has not been taken is not a number nobody needs. A row of the progress table read 0% for months; measuring it took an afternoon.
  5. Ask what a measurement cannot see. For a week every datapath figure was a transmit figure, while the receive path was broken badly enough that no download ever finished.

And the practice around them

  • Every measurement is photographed - the run, in its console window, the moment it finishes - and published with how it was taken, on a page of its own. A figure on a badge links to that page.
  • Only what was tested is claimed, and the claim names the build it was tested with.
  • Nothing private reaches the repository: no addresses, hardware addresses or serial numbers. A check fails any change that carries one in text; photographs are blurred by hand.
  • Facts are transcribed, expression is not copied - the boundary with the vendors' material, stated in docs/provenance.md.
  • A problem becomes an issue, and the issue carries what was learned from it.
  • Every page is dated with its last review, and a monthly check lists the ones that are due (docs/INDEX.md).
  • A changelog worth reading: every change sorted as a fix, an improvement or documentation, and a release made when a fix is ready or when improvements have gathered - never for every merge (chapter 11).

Home · Timeline

Discussion

The discussion of this page is held in the project's GitHub Discussions. Showing it here loads giscus from giscus.app and GitHub, and writing in it needs a GitHub account - what that means.