# Course Editorial Principles [中文版](course-editorial-principles.zh-CN.md) · [Unified curriculum design](course-design.md) · [Lessons](README.md) > **Status: v0.1, 2026-09-25.** This is the editorial contract for learner-facing K/L pages, lesson scripts, captions, and future experiment reports. It adapts the course-sharing principles used by the team to system identification. It does not replace the curriculum map, numerical experiment contract, or individual lesson review. ## Why this exists Robot system identification is easy to present as a sequence of equations, simulator settings, and plots. That presentation can be technically correct while leaving the learner unsure what to look at, what a result supports, or what to test next. This course should feel like a guided investigation. The learner sees a concrete mismatch, makes a prediction, changes a declared condition, reads the evidence, and states a bounded conclusion. The equation and the experiment serve that investigation. They do not become a chapter of definitions detached from a decision. The external course principles contribute the editorial discipline: start from an object, keep the learner independent of live teacher replies, separate demonstration from practice, label evidence honestly, and let each paragraph answer the question in front of the learner. The robotics course keeps its own technical identity: dynamics, signal visibility, identifiability, model mismatch, and operating envelopes remain central. ## Core proposition: from discrepancy to a bounded next experiment Every lesson is a small investigation with this movement: ```text observe a discrepancy → predict a cause or pattern → draw the system boundary → change one declared condition → read the evidence → state what it supports and cannot exclude → choose the next discriminating experiment ``` A lesson is successful when the learner can make and defend that judgment. Memorizing an equation, matching one curve, or accepting the lowest fitting loss is not enough. A valid conclusion may be a parameter estimate, a behaviorally useful model, a constrained range, or a reason to run a new experiment. ## Learner and narrator roles ### The learner is the investigator Write for a reader who is looking at a signal, diagram, table, or residual and deciding what it means. Ask for a prediction before supplying the explanation. Use “you” for an action the learner should take and make the evidence needed for that action visible. ### The instructor is a co-observer The narrator guides attention: “let us look at this mismatch,” “hold the posture fixed,” or “compare the held-out motion.” The narrator does not speak from an invisible all-knowing position or announce a conclusion before the evidence appears. When a run is real, explain its actual output. When it is an example or planned contract, say so. ### Oracle and Student are experimental roles `Oracle` and `Student` describe the synthetic system and the fitted candidate model. They are useful technical roles, not substitutes for “teacher” and “learner.” Keep the learner outside the experiment boundary: hidden truth can explain a result without becoming an input to fitting. ### Keep knowledge and access separate A fact may be known to the author, generated by the Oracle, visible to evaluation, or available to the fitter. Say which one it is. Do not let a diagram or an explanatory sentence quietly give the learner a signal that the declared experiment withholds. ## The common lesson rhythm The six-part page structure remains the course navigation, but each part has a narrative job: ### 1. Open with a visible mismatch Name the object and the surprising behavior. Use a concrete posture, motion, command, residual, or contact event. Avoid opening with a list of learning outcomes or a general promise. ### 2. Ask for a prediction before the equation Give the learner a small decision: what should change with posture, acceleration, velocity, delay, or contact? Then introduce only the symbols needed to explain that prediction. ### 3. Draw the boundary and derive just enough Show what enters the system, what is observed, what is hidden, and what is held fixed. Engineering derivations should expose units, dependencies, and assumptions. Full proofs belong in supplementary material unless the current judgment needs them. ### 4. Change one declared condition Keep the plant, controller, observations, and budget explicit. Vary one meaningful condition at a time when the lesson is isolating an effect. If several effects remain coupled, make that coupling the subject rather than pretending the comparison isolated more than it did. ### 5. Read evidence with a claim and a limit Make the learner connect an observation to a statement: ```text I expected … The plot or metric shows … Under these conditions it supports … It still cannot exclude … Next I would test … ``` Separate fitting, development, and final evaluation. A lower loss, a recovered parameter, a good held-out prediction, and better downstream control are different claims. ### 6. End with a discriminating next test Close by naming the remaining ambiguity and the smallest useful experiment that could separate it. “More data” is not a sufficient next step unless the lesson says which condition, signal, or motion adds information. K lessons may use conceptual or previously verified lab evidence to teach a judgment. L lessons apply the judgment to a declared experiment. Neither format should be forced to imitate the other. ## Voice and sentence rules - Start with a noun, action, or visible change: “the arm slows after reversal,” “joint 2 residuals grow when joint 1 accelerates.” - Use present-tense verbs and concrete subjects. Prefer “hold the posture fixed” to “posture should be held fixed.” - Use “we” for a guided observation and “you” for a learner decision. Use “the Student” or “the Oracle” only when referring to experimental roles. - Keep one paragraph focused on one observation, reason, or action. Split a long sentence when the listener would otherwise have to reconstruct the causal order. - Put caveats next to the claim they limit. Do not hide the operating envelope in a final disclaimer. - Do not prewrite a success line for an experiment whose output is not available. Narrate the actual curve, metric, or failure produced by the run. - Do not use distrust of AI, distrust of optimization, or distrust of a fitting method as a substitute for evidence. A method may be accepted when its conditions and evidence support it. The spoken version should sound like a colleague guiding an investigation. The page may use compact labels and tables; the script should connect them with natural transitions. Screen headings and short labels do not need decorative Chinese full stops. Complete explanations, questions, conditions, and answer guides keep the punctuation needed for meaning. ## Evidence language and status Every figure, number, clip, and claim uses one of these statuses: | Status | Meaning | Allowed language | |---|---|---| | Measured | Produced by the declared run and checked | “The run shows …” | | Replayed | A completed result is being viewed again without fitting | “The replay shows …” | | Conceptual | An explanatory drawing or illustrative curve | “This example illustrates …” | | Planned | A contract for a future runner or report | “The experiment will compare …” | | Diagnostic | Available to generation or explanation, excluded from fitting | “The Oracle diagnostic indicates …” | Do not call a conceptual comparison a result, or a planned plot evidence. When a new L page has no numerical runner yet, its page should state the contract, the expected reading, and the missing artifact in plain language. ## Equations and terminology Treat an equation as a map for a decision. Before or beside it, identify the input, observed output, unknowns, fixed quantities, units, and hidden diagnostics. Every symbol should earn its place by explaining a visible dependency or a boundary choice. At first use, introduce technical terms in stable English plus natural Chinese, for example `Student / 待辨识模型`, `Oracle / 真实系统`, and `held-out evaluation / 留出评估`. Later prose may use the shorter term. Explain the scope of terms such as “state,” “input,” “contact,” and “delay” in the current lesson rather than assuming that a familiar word has one universal boundary. ## Page and media contract The static page must stand on its own. It includes the question, the boundary, the evidence status, the exercise and answer guide, the limitation, and the next step. A video, notebook, or browser interaction may improve visibility, but it cannot carry the only explanation of what the learner should conclude. Demonstration and practice have different jobs. A replay can show where to look; an exercise asks the learner to make the judgment. A reference implementation is one acceptable implementation, not the definition of correctness. If the environment or simulator is unavailable, provide a fixed artifact and a path back to the real operation without claiming that watching it supplied hands-on evidence. Keep the shared six-part structure for navigation, but vary emphasis and length. A K page may spend more time on a diagram and a derivation; an L page may spend more time on a comparison and a residual. Consistency should make the course easier to enter, not make every page sound generated from one paragraph template. ## Bilingual contract English and Chinese pages share lesson IDs, equations, units, signal boundaries, evidence status, and claims. The Chinese page should read as a natural explanation for a Chinese-speaking engineer, not as a sentence-by-sentence substitution. The English page should keep stable searchable terms where they matter. When a content or evidence contract changes, update both narratives together. A translation may choose a shorter sentence or a more natural example, but it must not strengthen a claim, hide an uncertainty, or change whether a signal is fitter-visible, evaluation-only, or diagnostic. ## Refactor gate for existing lessons Before changing a page, identify the paragraph's current job and evidence status. Refactor in this order: ### Content Can a reader name the object, mismatch, and decision before meeting the general method? If not, move the concrete observation earlier. Does every equation explain a dependency or boundary? If not, shorten or move it to supplementary material. ### Voice Can the reader tell what the narrator is looking at, what the learner should predict, and what happens next? Replace distant claims about “the learner” with a direct observation or action. Keep “Student” and “Oracle” for model roles. ### Evidence Can a reader distinguish measured, replayed, conceptual, planned, and diagnostic material? If not, label the artifact before interpreting it. Remove any sentence that implies a run, report, or simulator result does not exist. ### Exercise Does the question contain enough visible evidence to answer? Does the guide explain the reasoning, a common wrong turn, a recovery path, and the condition for continuing? If not, the exercise is a prompt for guessing rather than a learning check. ### Translation Do the English and Chinese versions preserve the same boundary, claim, uncertainty, and next experiment? Check first-use terminology and the natural rhythm of the spoken version in both languages. ## Non-goals These principles do not make the course casual, remove equations, or force every lesson to have a video. Every lesson must still declare its media status (available, planned, or not needed) and provide static explanation plus usable evidence for its named question. They do not require artificial failures, a single correct interpretation, a fixed visual style, or a complete simulator before a contract can be taught. They do not replace numerical validation, independent learner acceptance, or lesson-specific technical review. ## Definition of done A refactored lesson is ready for review when: 1. its opening presents a concrete mismatch or question; 2. the learner makes a prediction before the main explanation; 3. the boundary and evidence status are visible; 4. the exercise can be answered from the page and its guide explains why; 5. the conclusion names both support and remaining uncertainty; 6. the next experiment is specific enough to change the diagnosis; 7. the English and Chinese pages preserve the same technical contract.