Docs
Update or create emout's bilingual (ja/en) documentation — README.{md,en.md}, docs/source/guide/*.{md,ja.md}, CLAUDE.md/AGENTS.md — keeping the pairs in sync, reflecting recent code or API changes, and verifying that readers can actually use the result. Use when the user asks to write, rewrite, translate, polish, extend, or reflect code changes in any doc, add a new guide page, or surface a new feature in the documentation.From its SKILL.md
npx -y skills add Nkzono99/emout --skill docsAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
17.8 KB, as published. Nobody here has run it
docs
Keep emout's bilingual documentation consistent and readable when adding or updating pages.
This skill adapts the Context Gathering → Refinement & Structure →
Reader Testing loop from Anthropic's doc-coauthoring skill to
emout's fixed surface (Sphinx + MyST, ja/en pairs, 8 guide pages today)
and borrows MUSUBI technical-writer's strict bilingual discipline. It
is procedural — do not ask the user questions unless a judgement call
genuinely needs their input.
When to use this skill
- The user asks to write, rewrite, translate, polish, or reorganise any doc.
- You just shipped a code or API change that needs to be reflected in the guides.
- You're adding a new guide page or feature section and want to wire it into the toctree and README at the same time.
- You notice drift between a ja/en pair (different examples, different section counts, stale version numbers) and want to resync.
Invoke run-tests separately when you touch code in addition to docs.
Canonical source per surface
.claude/rules/doc-pairs.md lists the pairs. Which side is the source
of truth matters because it decides where you type new prose first.
Japanese is canonical across the whole repo. emout's target audience
is Japanese-speaking EMSES users (see CLAUDE.md: やりとりの言語は
日本語), so every bilingual pair is authored Japanese-first and the
English version mirrors it.
| Surface | Canonical side | Mirror | Why |
|---|---|---|---|
docs/source/guide/*.ja.md | Japanese | docs/source/guide/*.md | Terminology, section order, tone, and example selection are decided on the Japanese side. EN mirrors the structure but should read as native English prose (not a literal translation). |
README.md (JA) | Japanese | README.en.md | Already Japanese-first. |
CLAUDE.md | Japanese | AGENTS.md | AGENTS.md is a literal copy; diff CLAUDE.md AGENTS.md must be empty. |
Rule of thumb: when writing new content, draft the Japanese version first, then produce the English mirror. When editing existing content, touch both sides in the same commit — never ship a half-update.
Note on existing history. Commit 067f1fe Improve Japanese docs: natural wording and sync with English reflects an older rule where EN
was the reference. That rule is superseded — but the guides written
under it are still in sync structurally, so no historical rewrite is
needed. Only new content and future updates follow the JA-canonical
rule.
Pages covered today: quickstart / plotting / animation / inp /
units / boundaries / backtrace / distributed. If you add
another, update .claude/rules/doc-pairs.md in the same commit.
Bilingual rules
These are load-bearing — follow them even when translating a single paragraph.
- Structure parity. Both language versions must have the same
section count, same heading levels, and same section order. Add a
section in one language → add it in the other in the same position.
Quick check:
diff <(grep '^#' guide/foo.md) <(grep '^#' guide/foo.ja.md)should be empty (modulo the heading text itself). - Code blocks are identical, prose is translated. Function calls,
variable names, keyword arguments, shell commands, Python identifiers,
EMSES parameter names (
phisp,nd1p,boundary_types,plasma.inp,remote_figure, …) are always English. Comments inside code blocks may be translated, but keep them short so line-for-line diffing still works. - Tables stay aligned. Column order, column count, and row order must match between ja/en. Only the content of description cells changes.
- Cross-links resolve to the same-language counterpart. If the
English guide cross-links to another guide, the Japanese guide
cross-links to the same guide's
.ja.mdfile — not back to the English one. - No half-translations. Don't leave an English paragraph inside
*.ja.mdbecause "it's clearer in English". Translate it, or cut it from both sides. - Version numbers, dates, file paths, numeric baselines are identical on both sides. When you bump the pytest baseline in CLAUDE.md, bump it in AGENTS.md in the same commit.
When writing Japanese prose, prefer natural wording over a literal translation. When writing English prose, write as a native English technical writer, not as a translator. Both versions should read as if each were the original.
Workflow
1. Context gathering
Goal: close the gap between what the code/repo knows and what the reader will need.
Before typing any prose:
- For a code-driven update: read the affected source (not the
docstring — the actual function body, its defaults, its exceptions).
Check
git logfor the last few commits in that area. If a public API changed, grep for every mention of it acrossdocs/source/guide/andREADME*.md— missing a call site is the most common failure of this workflow. - For a polish pass: read both language versions of every file you plan to touch before editing anything. Note existing terminology choices so you don't invent new variants mid-page.
- For a translation sync: structurally diff first
(
diff <(grep '^#' A) <(grep '^#' B)), then reconcile section by section. - Always: scan sibling guides for consistent terminology. New phrasing should match what the rest of the docs already use.
Ask the user only when:
- A judgement call affects the public API surface (e.g. "should I deprecate this or remove it?").
- You're about to delete a substantial chunk of existing content.
- The feature is experimental and the stability story is unclear from the code.
Exit condition: you can list, in your head, (a) which files you will touch, (b) the rough section structure of each change, and (c) which sibling pages need cross-link updates. Do not start writing prose until those three are clear.
2. Refinement & structure
Goal: produce content that reads well in both languages with structural parity guaranteed by construction.
Scaffold-first drafting. Never type the first paragraph of a new section before the section headers are in place:
- Draft the Japanese file first (
.ja.md). Terminology, section order, and tone are decided here. Use placeholder bodies like<!-- TODO: このセクションの目的 -->so structure is visible. - For a new page, use the scaffold in
.claude/skills/docs/templates/new-guide.ja.mdas the starting skeleton, and its English mirrortemplates/new-guide.mdfor the.mdside. Both match the structure of the existing 8 guides so new pages don't drift. - Fill one section at a time, in both languages, in lockstep. Write the Japanese section body first, then produce the English mirror immediately. Do not finish the Japanese page and then translate the whole thing later — by the time you come back you will have forgotten the choices you made.
- Write code examples once, paste into both files unchanged. Only the surrounding prose varies.
- Tables: headers and keys first, prose cells second. Build the skeleton on the Japanese side, copy it to the English side, then fill both in lockstep.
- Add cross-references last. They pay for themselves only after the structure is stable, and they are the #1 source of rebuild churn.
Brainstorm-before-curate. For any section covering more than one
point (a comparison table, a checklist, a tip block, a "common
mistakes" list), brainstorm 5–20 candidate entries before committing
any of them to prose. This is borrowed from doc-coauthoring: it
surfaces angles you would otherwise forget, and it keeps you from
writing filler to pad a section. After brainstorming, curate down to
what readers actually need.
Idiomatic emout phrasing (JA is canonical — pick the Japanese wording first, then mirror naturally in English):
- "EMSES シミュレーション出力" → "EMSES simulation output" (not "EMSES output data")
- "グリッドデータ" → "grid data" (not "field data" — reserve that for specific contexts)
- "境界" → "boundary" for finbound entries; "境界メッシュ" → "boundary mesh" when talking about rendering
- "リモート実行" → "remote execution" for the Dask path
- Keep
plasma.inp,plasma.toml,&ptcond,boundary_types, etc. in backtick-code font on both sides - "スライスの軸順序は
(t, z, y, x)" → "Axis order is(t, z, y, x)" — always mention this where indexing appears
Editing discipline. When modifying an existing page, use the Edit
tool for surgical diffs. Do not reprint the whole file with Write
unless the change is a near-total rewrite. This keeps review scopes
small and makes the doc history diffable.
Exit condition: both language files pass the structural diff check
(diff <(grep '^#' A) <(grep '^#' B)), all code blocks are
byte-identical, and every cross-link has been resolved at least once in
prose (even if anchor verification happens later).
3. Reader testing
Goal: confirm the docs actually work for someone who doesn't have your context. Build-clean is necessary but not sufficient.
3a. Build-clean. The minimum bar — do not skip:
cd docs
sphinx-build -n -b html -q --keep-going source /tmp/emout-docs-build 2>&1 \
| grep -iE "<file-you-touched>|myst\.xref_missing|local id not found"
Resolve every new myst.xref_missing or local id not found warning.
See Cross-reference gotchas below for the common traps.
3b. Verify cross-links resolve in the built HTML:
grep -oE 'href="[^"]*your-new-page\.html[^"]*"' \
/tmp/emout-docs-build/guide/related-page.html | head
3c. Reader testing with a fresh agent (recommended for new pages).
This is doc-coauthoring's core idea adapted to emout. Spawn an
Explore subagent that only sees the new/changed guide file(s) and
ask it to answer realistic questions. The subagent has no conversation
context, so it will trip over anything you explained-but-didn't-write.
Agent(
subagent_type="Explore",
description="Reader-test the new backtrace guide (JA)",
prompt="""
Read docs/source/guide/backtrace.ja.md only. Do not read any other file.
日本語でガイドを読み、emout を初めて触る日本語話者の視点で次の質問に答えてください:
1. 単一種の粒子について、ある観測点での到達確率分布を計算するにはどうすればよいか?
2. result.vxvz.plot() は具体的に何を描画する? result.plot_energy_spectrum() とは何が違う?
3. Dask を使ったリモート実行でも同じように動く? 何を変える必要がある?
4. fetch() は plot() と比べて何を手に入れるためのもの?
5. 初見のユーザーが最もハマりそうな点は?
各質問ごとに:
- 回答(1〜3 文)
- 不明瞭だった点 / ガイドが前提としている知識(1 文)
- 根拠になるガイド内の引用(1 行)
全体で 400 語以内。日本語で答えてください。
"""
)
After iterating on the Japanese version, run the same subagent against
backtrace.md to confirm the English mirror is equally legible to a
non-Japanese reader.
Use the subagent's answers to spot blind spots: anything it got wrong, any assumption-it-called-out, and any question it answered by inferring from a code example rather than from prose. Those are the holes you fix in another Refinement pass.
Default question templates for emout guides:
- Quickstart / feature discovery: "How do I X?", "What does the default do if I don't pass anything?", "What do I need installed first?"
- API reference-ish guides (backtrace, boundaries, units): "What does this function return?", "What are the required vs optional arguments?", "How does this interact with remote execution?"
- Workflow guides (distributed, animation): "What's the difference
between the compat mode and the explicit
remote()mode?", "When should I use action=X vs action=Y?", "What does this NOT support?" - Concept guides (plotting, inp, units): "What's the one thing I'll get wrong on my first try?"
Exit condition: build is clean, the subagent can answer the golden questions without "the doc doesn't say" or "I'm inferring from the example", and the structural parity check still passes.
Adding a new guide page
Follow this checklist in order.
- Copy
.claude/skills/docs/templates/new-guide.ja.mdtodocs/source/guide/<name>.ja.md. This is the canonical draft — edit the<...>placeholders first, don't write prose into a placeholder structure. - Copy
.claude/skills/docs/templates/new-guide.mdtodocs/source/guide/<name>.mdas the English mirror scaffold. - Fill sections in lockstep, Japanese first then English mirror, one section at a time.
- Register in
docs/source/index.rstunder theUser Guidetoctree. Japanese entry first, mirroring existing order:guide/<name>.ja guide/<name> - Add
<name>to.claude/rules/doc-pairs.mdin the comma-separated list. - Surface in both README feature tables. URLs:
https://nkzono99.github.io/emout/guide/<name>.ja.htmlandhttps://nkzono99.github.io/emout/guide/<name>.html. - Cross-link from one or two related existing guides (ja/en pair-to-pair). Don't scatter links everywhere — pick the pages a reader would naturally land on first.
- Run the reader-testing workflow (§ 3 above). For a brand-new page, run the subagent step against the Japanese version first (that is what real readers will open) and then optionally against the English version.
- Run
pytest -qif the feature you documented also has runtime code changes; pure docs changes skip this.
Reflecting code changes into docs
When a code change ships and the docs need to catch up:
- Find every affected guide. Grep for the symbol/API name across
docs/source/guide/andREADME*.md. Missing a file is the most common failure mode. - Update in pairs. Never commit an update to
foo.mdwithout the matching update tofoo.ja.md. If you notice the pairs have already drifted, resync them first as a separate edit (easier to review). - Update every spot where the old behaviour is described, not just the first one. Use grep, not memory.
- Refresh code examples. If a signature changed, the example must compile against the new signature. Copy-paste the updated example into both language files so they stay byte-identical.
- Bump obvious counters. The
pytestbaseline in CLAUDE.md and AGENTS.md is the most common one. - Reader-test at least the changed section with a subagent if the API surface moved meaningfully (new kwarg, new return type, new error mode). Build-clean alone does not catch "my explanation doesn't match the new signature".
Cross-reference gotchas
MyST + Sphinx has a few specific traps. Learning them once saves a rebuild cycle each time.
- Internal doc-to-doc links.
[text](other.md)works and resolves toother.htmlin the build. For the JA side use[text](other.ja.md). - Anchor links across files require a Sphinx label, not a slugified
heading.
[text](other.md#my-section)will usually emitmyst.xref_missing. If you want deep linking:- add an explicit label above the heading and reference it with
Sphinx's
{ref}role (not standard Markdown), or - drop the anchor and link to the page top, describing the section by name in prose — "see the "Remote execution" section of the animations guide". This is what the repo currently uses and what you should default to.
- add an explicit label above the heading and reference it with
Sphinx's
- Japanese headings get ASCII-stripped slugs. A heading like
## リモート実行(Emout.remote())becomes#emout-remotein HTML. Anchor linking against it is fragile; prefer prose references. - Do not link to
../api/*.rstfrom a guide. Those are Sphinx sources, not the built pages. Either describe the class in prose with backticks and let readers navigate via the API sidebar, or (rarely) use Sphinx's{doc}role — the repo does not use it today. - Code blocks with triple backticks and braces. Literal
{}inside a triple-backtick block needs no escaping. Only MyST role syntax ({role}`text`) needs braces escaped.
Common mistakes
- Editing only the canonical side because "I'll mirror it later." You won't — do both sides in the same commit.
- Translating code identifiers.
data.phispis notdata.電位. APIs and parameter names are universal. - Mismatched section counts because you added a subsection in one file and forgot the other. The structural diff check exists for this reason — run it.
- Stale
doc-pairs.mdafter adding a new guide. The list is small, update it in the same commit. - Forgetting the README feature table. A new guide that's not in the README table is effectively hidden — users won't find it.
- Skipping reader testing for "obviously clear" changes. The changes that feel obviously clear to you are exactly the ones where a fresh reader will ask the question you thought you answered.
- Reprinting an entire file with
Writefor a one-paragraph change. UseEdit— review scopes stay small and history stays diffable. - Committing
docs/build/. It's a build artifact; never stage it.