Skip to content

docs: drop closed-issue citations, and credit parcagpu in one place - #210

Merged
dpsoft merged 1 commit into
mainfrom
docs/refs-and-credit
Oct 18, 2026
Merged

dpsoft merged 1 commit into
mainfrom
docs/refs-and-credit

Conversation

@dpsoft

@dpsoft dpsoft commented Oct 17, 2026

Copy link
Copy Markdown
Owner

Two unrelated things a reader notices and a writer does not.

Issue numbers

The user docs cited eight issues. Six were closed, so clicking one landed
on resolved work that explained nothing the paragraph had not already said.

The rule applied: cite an issue when the reader can act on it — an open
limitation they might hit. Otherwise it is archaeology. So the closed ones
are gone from docs/, examples/ and the README, and #194 stays in both
places it appears, because it is open and names a limit a reader will meet.

The CHANGELOG keeps all of its references untouched. That is the historical
record; the numbers belong there.

One of them was not archaeology but a live falsehood #209 missed. The
examples table still read "Not runnable yet — see #121" for kubernetes/,
while the prose three lines below already said the opposite. Fixing the prose
and leaving the table is how a document ends up contradicting itself inside
one screen.

parcagpu

The injection pattern is theirs and we took it directly, so the credit stays.
But it opened the section meant to explain our own two deployments, and
their name appeared three times before a reader learned how to use either of
ours. That reads as a comparison piece rather than a how-to — and it buries
the attribution inside an argument instead of simply stating it.

It is now a short Prior art section of its own, before anything else: the
pattern is theirs, we took it directly, this document is what we do inside
it.

The privilege comparison keeps every number it had — hostPID, privileged,
CAP_SYS_ADMIN — and moves under a heading that says what it is for, at the
end of the deployments section rather than interleaved with them.

No claim changed. "Neither deployment is zero-touch", including the note
that Parca is in the same position (their CPU profiling is
zero-instrumentation, their GPU profiling is not), stays exactly where it
was.

Every link in the touched files still resolves, and the [ps] reference is
still both used and defined.

Two unrelated things a reader notices and a writer does not.

ISSUE NUMBERS. The user docs cited eight issues; six were closed, so
clicking one landed on resolved work explaining nothing the paragraph had
not already said. Citing an issue is useful when the reader can act on it —
an open limitation they might hit — and is archaeology otherwise. The
closed ones are gone from docs/, examples/ and the README; #194 stays in
both places it appears, because it is open and names a limit a reader will
meet. The CHANGELOG keeps all of its references: that is the historical
record, where the numbers belong.

One of those was not archaeology but a live falsehood #209 missed. The
examples table still read "Not runnable yet — see #121" for kubernetes/,
while the prose three lines below already said the opposite. Fixing the
prose and leaving the table is how a document ends up contradicting itself
in the same screen.

PARCAGPU. The injection pattern is theirs and we took it directly, so the
credit stays — but it opened the section meant to explain OUR two
deployments, and their name appeared three times before a reader learned
how to use either of ours. That reads as a comparison piece rather than a
how-to, and it buries the attribution in argument rather than stating it.

It is now a short "Prior art" section of its own, before anything else:
the pattern is theirs, we took it directly, this document is what we do
inside it. The privilege comparison keeps every number it had and moves
under a heading that says what it is for, at the end of the deployments
section instead of interleaved with them.

No claim changed. "Neither deployment is zero-touch", including the note
that Parca is in the same position, stays exactly where it was.
@dpsoft
dpsoft merged commit c1a43c7 into main Oct 18, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant