[Docs] CONTRIBUTING promises English dartdoc on public types; 60% is Dutch #625

New issue

Closed

opened 2026-07-22 16:21:53 +00:00 by brenno · 1 comment

brenno commented

2026-07-22 16:21:53 +00:00

Owner

Found in the pre-publication architecture review.

Evidence: CONTRIBUTING.md:113-116 states that English is "the natural choice" for "API doc comments on a public type". Measured across every public class/enum/mixin/extension in lib/, excluding l10n: 299 Dutch against 199 English (60% Dutch). In lib/services/ it is 155 / 69 (69% Dutch); in lib/state/ 22 / 7. Across all /// lines: 9,998 Dutch / 4,104 English (71%).

Why this matters now: dartdoc is what dart doc, pub.dev and the IDE hover display — the only layer of this codebase an outsider consumes without reading the code. The rule now exists and the code does not follow it at the one point where the rule specifies English, which reads as a contributing guide describing an intention rather than a practice.

Related to #518, which noted there was "no rule"; there is one now, and this is the gap between it and the tree.

Proposal: do not translate 299 doc comments — CONTRIBUTING.md:117-120 rightly forbids that. Narrow the clause to what you will honour: new public types in lib/models/ and lib/services/ get English dartdoc, with a counter in check_conventions.dart set at the current figure as a ceiling. On top of that, translate only the 54 public types in lib/models/ — the data layer, the smallest and most-read set. If neither is going to happen, delete lines 113-116; leaving them costs more than not having them.

Found in the pre-publication architecture review. **Evidence:** `CONTRIBUTING.md:113-116` states that English is "the natural choice" for "API doc comments on a public type". Measured across every public `class`/`enum`/`mixin`/`extension` in `lib/`, excluding l10n: **299 Dutch against 199 English (60% Dutch)**. In `lib/services/` it is 155 / 69 (69% Dutch); in `lib/state/` 22 / 7. Across all `///` lines: 9,998 Dutch / 4,104 English (71%). **Why this matters now:** dartdoc is what `dart doc`, pub.dev and the IDE hover display — the only layer of this codebase an outsider consumes *without* reading the code. The rule now exists and the code does not follow it at the one point where the rule specifies English, which reads as a contributing guide describing an intention rather than a practice. Related to #518, which noted there was "no rule"; there is one now, and this is the gap between it and the tree. **Proposal:** do not translate 299 doc comments — `CONTRIBUTING.md:117-120` rightly forbids that. Narrow the clause to what you will honour: **new** public types in `lib/models/` and `lib/services/` get English dartdoc, with a counter in `check_conventions.dart` set at the current figure as a ceiling. On top of that, translate only the 54 public types in `lib/models/` — the data layer, the smallest and most-read set. If neither is going to happen, delete lines 113-116; leaving them costs more than not having them.

brenno added the

docs

label

2026-07-22 16:21:53 +00:00

brenno referenced this issue from a commit

2026-07-22 17:07:10 +00:00

docs: maak het bijdragerspad waar wat het belooft (#588 #625 #642 #596 #595 #594)

brenno referenced this issue from a commit

2026-07-22 17:12:52 +00:00

docs: maak het bijdragerspad waar wat het belooft (#588 #625 #642 #596 #595 #594)

brenno referenced this issue

2026-07-22 17:13:34 +00:00