8.5 KiB
name, description
| name | description |
|---|---|
| bpf-tutorial-writing-style | Repository-local prose and bilingual checklist for drafting, rewriting, or reviewing advanced bpf-developer-tutorial README.md and README.zh.md files. Use to match the readable voice of 49-hid and the useful depth of 47-cuda-events while preserving implementation facts, complete source, commands, evidence, caveats, and references. |
BPF Tutorial Writing Style
Use this Skill for writing quality only. Use $write-bpf-production-tutorial for build, KVM, exact-source checks, and PR steps.
Read all three references before drafting or reviewing:
- Advanced tutorial guidelines contains the complete project-provided requirements and must remain intact.
- Repository house style explains how to learn from existing tutorials without copying their defects.
- Prose and bilingual checklist carries the relevant eunomia.dev writing discipline into this repository.
Also read the English and Chinese versions of 47-cuda-events and 49-hid in full. Existing lessons are examples of rhythm, depth, and teaching order, not templates. Verified code, real output, primary sources, and the user's requirements remain authoritative.
Write for a reader
Start with a short, truthful scene the reader can picture. Show one observable problem or useful action, then raise the technical question that the lesson will answer. Keep one example, packet, event, task, device interaction, or failure as the thread through the article, so the opening scene returns naturally when the code and output are explained.
Treat the scene as a teaching device, not a license to write fiction. Do not invent a named operator, customer, outage, deployment, benchmark, urgency, or result. If the implementation is a bounded lab tool, make the scene a bounded lab situation and let the real mechanism make it interesting.
Give the feature a place in the series
After the scene, identify the lesson once as part of the eBPF Tutorial by Example series. Give the reader a short ladder from eBPF to the example: explain the relevant verified-program and user-space attachment model, introduce the specific hook or subsystem, state the first Linux release that added the enabling feature, and say what became possible in that release. Close the background by pointing to the exact operation performed by this lesson.
Keep the ladder to one or two compact paragraphs and select only concepts the later code uses. A lesson built from several new capabilities should name each release boundary and show why the capabilities work together. Put commit hashes, full configuration lists, and detailed compatibility evidence in the later requirements and references sections, while the opening keeps the version, capability, and causal link readers need before the code.
Use oral English, familiar words, and connected sentences. Write natural Chinese independently from the same facts. Chinese punctuation should be restrained: prefer one or two connected sentences that carry one technical thought over a row of short, period-heavy statements. Prefer causal explanation over inventories. A paragraph should tell the reader what happens, why it happens, and what that enables.
Prefer positive, concrete statements throughout the tutorial. Explain what the hook, program, loader, command, or test does and which scope it covers. Rewrite not, do not, cannot, will not, 不要, 不能, 不会, 并非, and 别 whenever the same fact has an accurate positive form, and remove every double negative. Keep at most one compact boundary paragraph near the end, limited to two sentences, instead of distributing failure, limitation, and safety warnings through the article.
Keep the actor close to the action. Start important sentences with a concrete component, use active voice when ownership matters, connect short facts through cause and effect, and give this, it, 这 and 它 an unmistakable referent. Put the claim before detailed evidence, use verbs instead of abstract noun phrases, and end a sentence on the new fact the reader should remember.
Do not write like a paper, specification, PR description, release note, test log, or compliance report. Build and KVM evidence belongs in compilation and execution, where it should support a claim instead of becoming the article's main plot.
Draw the relationship when prose starts carrying a graph
Use a small technical diagram when the running example crosses at least three dependent states, branches and later rejoins, waits and retries, transfers ownership, or connects one component to several consumers. The diagram should let the reader see a relationship that would otherwise require rereading a paragraph. Keep a simple linear filter, a single hook, or a two-step command in prose.
Build diagrams from verified code and tests. Prefer code identifiers and short labels, one clear direction, restrained color, and enough whitespace to read the figure at ordinary README width. Introduce the figure with the concrete packet, event, task, or device interaction already used in the story, then explain the decisive branch or ownership change after the image. A diagram supports the narrative; it does not replace the source walkthrough.
Keep the editable DOT, Mermaid, or SVG source beside the rendered PNG. Use descriptive alt text and a canonical absolute GitHub target for the image. A language-neutral figure can serve both README files when code identifiers carry the flow; prose-heavy labels call for matched Chinese and English assets.
Keep the source readable
Include complete core source exactly as implemented. Teach one component at a time: introduce its role, present its source inline, and immediately explain the important logic before moving on. Do not hide source in <details> and do not separate a long source dump from all of its explanation.
Do not simplify code, insert ellipses, or rewrite comments. Present complete source in ordinary Markdown fenced code blocks without HTML synchronization markers, then verify it against the real file.
Place one complete-source callout near the opening and link only the lesson's GitHub directory. Let the directory serve as the entry point for source, build files, fixtures, and tests, while later component sections name individual files beside their complete code blocks.
Use canonical GitHub absolute URLs for every other Markdown link, even when the target belongs to the current lesson. Never use ./, ../, or another host. If no stable GitHub URL exists, leave the text unlinked. This rule overrides link patterns in older lessons and the website call to action in the advanced guidelines.
Keep local infrastructure private. Do not name workspace paths, shared lab repositories, VM instances, copy routes, caches, or agent trace locations in a tutorial or PR description. Retain only public reproducibility facts such as architecture, kernel version and commit, configuration, commands, and captured output.
Keep scope honest
Describe what the implementation actually provides. A bounded lab command is a bounded lab command. Do not inflate it into a daemon, controller, production scheduler, security product, or operational platform.
State requirements and explain cleanup through the normal lifecycle. Collect failure conditions, limitations, and safety boundaries into one compact paragraph of at most two sentences near the end. Move low-level kernel provenance into a compact requirements or reproducibility note.
Final reader check
Read the finished lesson in order once. The reader should be able to answer:
- What concrete problem does this lesson solve?
- How does one packet or event move through kernel and user space?
- Which eBPF mechanism makes that possible?
- Which code deserves close attention?
- How do I build, run, and recognize success?
- What does the captured output prove?
- Where does the example stop?
Revise if the reader instead encounters a code wall, repeated disclaimers, a validation transcript, dense spec-sheet paragraphs, literal Chinese translation, or a scenario larger than the tool. This reader check is a judgment pass, not a reason to add reviewers or models.