Write manual.md from the source material. Assume the reader is "a middle school student who knows nothing at all about the field." Success means the reader can reach the end without stopping along the way; anything else is considered failure.
Overall Flow
- Read the source material — determine what can be stated as fact
- Decide the reader and the goal
- Break it into steps
- Write (place code and images here with supporting evidence)
- Japanese check(natural-japanese) → fix
- claat lint → hand off to the user
Do not skip 5 and 6 before handing off. Fixing the Japanese can shift lines and break image paths or the position of Duration , so always run 6 after 5.
1. Read the Source Material
If the target directory or materials are not specified, ask first. Once specified, read README, entry points, configuration files, existing documentation, and task definitions such asTaskfile や package.json with priority.
Decide only one thing here.What facts may be written in this procedure document。
- Write only the commands, paths, versions, and outputs that can be confirmed from the source material
- Do not write anything that cannot be confirmed. If you want to write it, ask the user or explicitly mark it as "(unconfirmed)" and leave it in the draft
- If you mix in even one guessed command, the reader will get stuck there and stop trusting the entire procedure document. The value of a procedure document rests only on accuracy
2. Reader and Goal
Before starting to write, articulate the following three things at the beginning. If you cannot write them, the source material is insufficient.
- Reader: What does this person know, and what do they not know?
- Goal: If they proceed to the end, what will they be able to do?
- Prerequisites: What must be in place before entering the steps (equipment, accounts, installed items)
Do not mix prerequisites and steps. "Prerequisites" are what the reader prepares in advance, and "steps" are what is done within this document; if mixed, the reader will lose track of where they are.
3. Break into Steps
1 step = 1 verifiable state change. This is the only criterion for how to divide them.
The reader can interrupt the work at the end of any step. Therefore, at the end of each step, there must be a state where the reader can tell "if it is like this now, it succeeded," and any unit for which that cannot be written is either too large or too small as a step.
- Example of too large: "Set up the environment" (you cannot tell how far you need to go for success)
- Example of just right: "Install Go and
go versionConfirm that 」 is displayed - Example that is too small: "Open the terminal" (there is no state change to confirm on its own)
The first step must always be "Confirm the goal and prerequisites." Readers start reading while anxious about whether they have opened the correct document, so resolve that first. The last step should be "Confirm what you accomplished" and contact information.
Duration is used to check whether the division is correct. If a step takes more than 15 minutes, it usually contains two or more state changes. Estimate the actual time honestly, and0:05:00 do not fill it in with round numbers like .
4. Write
4-1. Conditions for sentences that middle school students can understand
The reason readers get stuck is not vocabulary, butcontext omitted by the writer. Follow these.
| Principle | Reason |
|---|---|
| One action per sentence | If you write two, you make the reader decide which to do first |
| Write "where" first | "In the terminal, run the following." If readers read the verb without knowing the location, they stop |
| Paraphrase technical terms on the spot where they first appear | If you send readers to a glossary, they will not come back. "CFW (a mechanism that allows unofficial tools to run on the 3DS)" |
| After an operation, write "if it looks like this, it succeeded" | Without this, readers proceed to the next step without noticing failure |
| Do not use "it" or "here"; refer by name | Write button names and file names on the screen exactly as they are |
| Use polite form (desu/masu) consistently | If you drop into plain form midway, it reads as if someone else wrote it |
4-2. When to include code
There is one criterion.Is it something the reader must reproduce exactly. Put things to reproduce in code blocks, and write explanations in prose.
| Purpose | How to write |
|---|---|
| Commands to run | ```console one command per line in .$ や > Do not include the prompt symbol in (it gets in the way when readers copy and paste) |
| Content to paste into a file | ```go Add a language name like . State the file path in the prose immediately before |
| Output expected to appear on screen | ```text. This is for readers to compare against, so include the actual output string exactly as it appeared |
| Overall picture / structure diagram | ```text Draw it with arrows inside . It is faster than making a diagram and easier to fix later |
Do not paste an entire long file. Show only the lines to change and 2-3 lines before and after them. What readers are looking for is the diff, not the full text.
Do not include unverified code. Commands that cannot be verified from the source material are dangerous precisely because they can be written plausibly, and that is where readers get stuck.
4-3. When to include images and screenshots
Images have only two jobs.To show "which one to press"と、To let readers verify "whether this is correct". Do not include anything other than these two.
Include
- When the GUI element to operate cannot be identified by name alone (icon-only buttons, multiple elements with the same name)
- When you want readers to verify "what the correct state looks like" (e.g., whether the settings screen opened correctly)
- When you want to show the relationship between steps first (→ but this is often sufficient with a
```textdiagram)
Do not include
- Commands, paths, setting values, error messages. If turned into images, they cannot be copied and will not be found by search. This harms readers
- Decorative screenshots. Readers stop and wonder "what am I supposed to look at here?"
How to capture and how to write
- Capture only the range necessary for the operation. Do not capture the entire desktop
- Mask personal information, tokens, and internal host names
- The save location is
manual.mdin the same directory asimages/. Reference with a relative path - In the alt text, write not "what is shown" butwhat you want readers to verify.
rather than
When the image does not exist yet, do not write its path. claat lint checks that relative images actually exist, so writing a path you intend to add later will stop the build. Instead, separately from the end of the document,shooting request listpresent to the user.
撮影をお願いしたい画面（撮れたら images/ に置いてください）
- images/step3-settings.png : 「詳細設定」タブを開いた状態
- images/step5-result.png : ビルド成功時のターミナル表示
4-4. Notation that claat interprets (actually generated and verified)
In addition to plain Markdown, claat interprets the following. Using it helps readers, but a procedure document still works without it.
Note box. in the claat parser README Positive と : 本文 The two-line form ofdoes not work in the claat version pinned by claat-tools。<p>Positive : 本文</p> and becomes a plain paragraph. Use either of the following.
> aside positive
> 時短のコツやベストプラクティスを、緑の枠で出します。
> aside negative
> 警告や、やってはいけないことを、赤い枠で出します。
Writing HTML directly produces the same result.
<aside class="negative">
警告や、やってはいけないことを、赤い枠で出します。
</aside>
Download button. <button>[Download SDK](https://example.com)</button> is rendered as a button.
Checklist heading. ### What you'll learn ### What we've covered ### Frequently asked questions Bullet points underthe English heading string itselfare rendered as a checklist. However, this determination is made against### 学ぶこと . If you want to use it in a Japanese procedure document, you would have to make only the heading English, but ordinary bullet points convey it well enough for readers. Decide based on the content whether it is worth making the heading English just to use it.
Tables, links, and lists follow normal Markdown.
4-5. Writing that fails claat lint (confirmed in implementation)
cmd/claat-tools lint is stricter than claat itself. The following are especially easy to trip on.
DurationはH:M:SSrequires 3 separators。claat は5:00is accepted, but this lint rejects it.0:05:00write it as- If the body of a step consists only of a code block,
STEP003it fails with. The lint does not count inside the fence as body text. Always place one line of prose before the code. DurationIf there is a code fence beforeSTEP002。##the first non-blank line immediately afterDurationmust be#####The following headings cannot be used.#######up to#There must be only one title. Anything before it is the metadata area, andkey: valueplacing any line other than that will fail- Metadata is fixed at 7 keys.
tagsやauthorsAddingMETA002 idは[A-Za-z0-9][A-Za-z0-9_-]*. Japanese and slashes cannot be usedenvironmentsはWebかKioskonly,statusはDraft/Published/Deprecated/Hiddenonly
The template is assets/template.md. Copy this to the output destination, then replace all placeholders. Do not leave the explanatory text as is.status If not specified, Draft。
5. Japanese check (always before delivery)
The Japanese at the time you finish writing usually contains "repetition of the same template" and "translationese." Since you cannot notice it yourself, have a machine detect it.
Procedure
-
Duration:Create a copy with the lines replaced by blank lines.Duration:appears dozens of times per document, so if left as is,repeated_sentence_leadfalse positives bury the real findings (measured: 32 vs. 11). Since you want line numbers to match the original file, replace with blank lines rather than deleting.sed 's/^Duration:.*$//' manual.md > .prose-check.md -
natural-japaneseCall the skill in quick mode, with.prose-check.mdas the target. Specify the document type as "internal guide/manual" and the genre astech. If the output is garbled on Windows, addPYTHONIOENCODING=utf-8. -
A finding is a "presentation of suspicion," not an instruction to fix.Judge and record each one as "fixed" or "left as is (reason)." In procedure documents, the following judgments often come up.
- Fixed repetitions such as "as follows ~" or "~ will be displayed"are left as is. In procedure documents, aligning sentence patterns lowers the reader's burden, so breaking them for the sake of variety makes them harder to read
- Long sentences, sentences containing two actions, or distant dependenciesare fixed. This connects directly to the principles in 4-1
- Translationese / prohibited words("you can ~" "one could say that ~") are fixed. In procedure documents they are merely verbose and add no information
-
After fixing, reflect it in the original
manual.md, and.prose-check.mddelete it.
6. Pass claat lint
Always run it after fixing the Japanese.
go run github.com/nogikun/claat/cmd/claat-tools@v0.1.0 lint path/to/manual.md
Fix until the exit code becomes 0. Reading error codes and HTML generation are handled by the claat-build skill, so here you only need to confirm that lint passes.
7. Hand over to the user
Communicate the following three things.
- The saved path
- Parts left unverified (if any) and what you want confirmed
- The shooting request list (the one raised in 4-3)
If not requested, do not generate HTML or publish.