Repository navigation
docs: drop closed-issue citations, and credit parcagpu in one place - #210
Merged
Merged
Conversation
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.
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
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.
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 bothplaces 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 theend 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 isstill both used and defined.