docs(README): trim noisy intro + use-case + architecture prose#16
Merged
Conversation
…re prose Three passages were doing more work than they earned: - **Intro** mixed pitch (CPU/off-CPU/PMU + pprof) with implementation detail (FP+DWARF, Python -X perf, Node.js --perf-basic-prof) and ran across two paragraphs. Reader had to parse a lot to extract "what is this, where does it run." Now one sentence: capture these profiles, emit pprof, run locally, no backend. - **--inject-python use case** had a four-clause sentence covering trampoline activation semantics, sidecar k8s deployment shape, shareProcessNamespace flag, kubectl cp egress. The deployment cookbook bits are duplicated by the dedicated 🐳 Sidecar use case below. Trim to the actual value prop: hot-attach without restart, trampoline only for the capture window. - **Architecture prose** under the ASCII diagram explained MMAP2 watchers, Go-binaries-lack-.eh_frame fallback, ehcompile→ehmaps installation, per-PID lazy procmap caching. All true and load-bearing for a contributor; not value-prop for a reader picking up the README. Compress to two sentences: which flag selects which walker, and what the procmap.Resolver buys you (-diff_base + sample-PGO). No new files, no link-outs to a separate architecture doc. Reader who wants the depth opens the code. Net: −9, +4. README drops to 434 lines.
…il, library variants A through F from the iteration list: - A. Drop Usage > "Profiling running Python processes" and "Profiling inside a Kubernetes pod" subsections. Both restated what the 🔥 and 🐳 use cases already cover; the Python one duplicated detail that lives in docs/python-profiling.md. Replace with a one-line pointer. - B. Trim Output > "pprof fidelity" from a 5-paragraph reference enumeration of every Mapping/Location field to two sentences that state what the consumer cares about (real per-binary identity, file-offset Locations, [kernel]/[jit] sentinels, tags + labels). - C. Library usage: keep the canonical example, drop the in-memory collection and custom-label-enricher sub-blocks. Both were one- option-each illustrations that the package docs already cover. - D. Drop "Real workflows perf-agent is built for. Each maps to one or more of the modes documented under [Flags]." — meta-commentary the section title already conveys. - E. Light cuts on use-case prose: drop "Output is pprof, viewable in go tool pprof or any flame-graph tool" (already established), drop "all inlined frames expanded by blazesym" (impl detail), drop "without the perf stat parsing tax" (comparative aside), drop the /proc/<N>/status NSpid mechanism explanation in the sidecar use-case (impl detail), simplify "two PCs that symbolize to the same (file, line, func) stay distinguishable" to "address-stable across runs." - F. Tagline + intro paragraph were saying the same thing. Keep the tagline (italic, distinct visually); the intro becomes just the deployment line: "One binary, runs locally, no backend or telemetry." Net: -94 / +13. README drops to 353 lines. Every cut is duplicate, reference material that has a home elsewhere, or implementation noise that doesn't help a reader pick up the tool.
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.
Iteration on the README that lands now that #15 is in. Three passages were doing more work than they earned; this PR trims them.
Changes
1. Intro paragraph
Mixed pitch with implementation detail across two paragraphs. Now one sentence.
```diff
```
The dropped tech detail (FP+DWARF, Python `-X perf`, Node.js `--perf-basic-prof`) still lives in the use-case section and Flags table — readers who want to know how find it; readers who want to know what aren't ambushed with it.
2. `--inject-python` use case
Four-clause sentence covering trampoline semantics, sidecar deployment, `shareProcessNamespace`, and `kubectl cp`. The deployment shape duplicates the 🐳 Sidecar profiling inside Kubernetes pods use case lower down. Trim to the actual value prop.
```diff
```
3. Architecture prose
Compressed two dense paragraphs (MMAP2 watchers, eager-compile fallbacks, ehcompile→ehmaps installation, per-PID lazy caching) into two sentences. The architecture diagram stays; the prose around it now states which flag selects which walker, and what `procmap.Resolver` buys downstream tools.
```diff
```
No new files, no link-outs. Readers who want depth open the code.
Diff shape
```
README.md +4 / −9 (439 → 434 lines)
```
Status
Draft. Iterating — happy to keep cutting if you point at more passages that don't earn their keep.