Evidence is the concrete support that lets readers test a technical claim or reconstruct a failure. It includes personal experience, code examples, experiments, benchmark results, monitoring data, charts, scripts, and trusted industry knowledge. Treat arguable statements as unfinished until enough evidence lets a skeptical reader reach the conclusion independently. section 5.2.1 section 8.4.3
Use evidence to replace assertion with something a reader can inspect:
- Replace an impressive performance claim with fair before-and-after benchmark results. section 5.2.1
- Replace a language comparison with representative code examples. section 5.2.1
- Replace “migration is simple” with the required steps and conditions that create complexity. section 5.2.1
- Replace “the code smells” with the problematic code and an explanation of the suspected antipattern. section 5.2.1
A bug hunt built from evidence
A performance investigation might show database monitoring graphs, CPU and disk statistics, flame graphs, build timings, tracing data, attempted fixes, dependency graphs, or memory-pressure tests. These artifacts let readers follow the investigation and form hypotheses before the explanation reveals the cause. section 8.4.3
Table 5.1 Supporting arguable statements with facts (view table figure)
| Instead of just stating |
Do this instead (or in addition) |
|---|---|
| “This optimization yielded an impressive performance boost.” |
Share the results of fair benchmark tests (before and after). |
| “NewLanguage is more intuitive than OldLanguage.” |
Share NewLanguage vs. OldLanguage code examples. |
| “ShinyNewThing is worth a try.” |
State: “Our experiences with ShinyNewThing showed that …” |
| “It’s difficult to do [this thing].” |
Explain: “Doing [this thing] requires you to deal with [all these other things],” or “We really struggled with [these hard details].” |
| “Migration is simple and seamless.” |
Detail the steps required and also call out any conditions that could introduce complexity. |
| “The code clearly smells.” |
Highlight the problematic parts of the code and explain why it can be considered an antipattern. |
Use the comparison table as a quick revision test: find each arguable statement and attach a result, example, experience, explanation, or other concrete support. section 5.2.1
