Write manual.md from the source material. Assume the reader is "a middle school student who knows nothing at all about that field." Success is if the reader can reach the end without stopping partway; anything else is considered a 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 placement of Duration , so always run 6 after 5.
1. Read the Source Material
If the target directory or materials are not indicated, ask first. Once indicated, prioritize reading README, the entry point, configuration files, existing documentation, and task definitions such asTaskfile や package.json .
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
Verbalize the following three things at the beginning before you start writing. 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 starting 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 looks 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 must 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 right 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 exceeds 15 minutes, it usually contains two or more state changes mixed together. Estimate the actual time honestly, and0:05:00 do not fill it in with a round number 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 the rules below.
| Principle | Reason |
|---|---|
| One action per sentence | If you write two, readers are forced to 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 at first mention | 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 forms (desu/masu) consistently | If you drop into plain style 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.$ や > Do not include the prompt symbol (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. Since this is for readers to compare against, include the actual output string exactly as it appeared |
| Overall picture / configuration 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 the reader verify "is this correct?". Do not include anything other than these two.
Include
- When the GUI operation target cannot be identified by name alone (icon-only buttons, multiple items with the same name)
- When you want the reader to verify the "correct appearance" (for example, whether the settings screen opened correctly)
- When you want to show the relationship between steps first (→ but this is often sufficient with the diagram in
```text)
Do not include
- Commands, paths, setting values, error messages. If made into an image, they cannot be copied and will not be found by search. This harms the reader
- Screenshots for decorative purposes. 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 it with the relative path - In the alt text, write not "what is shown" butwhat you want the reader 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 if you write a path you intend to add later, the build will stop. Instead, separately from the end of the document,shooting request listpresent a to the user.
撮影をお願いしたい画面（撮れたら images/ に置いてください）
- images/step3-settings.png : 「詳細設定」タブを開いた状態
- images/step5-result.png : ビルド成功時のターミナル表示
4-4. Notation interpreted by claat (actually generated and verified)
In addition to plain Markdown, claat interprets the following. Using it helps the reader, 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 under are rendered as a checklist. However, this determination is made againstthe English heading string itself, so it does not work for Japanese headings like### 学ぶこと . If you want to use it in a Japanese procedure document, you would have to make only the heading English, but an ordinary bulleted list conveys 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 style 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:SSmust have 3 segments。claat は5:00is accepted, but this lint fails it.0:05:00write as- If the body of a step is only a code block,
STEP003fails. The lint does not count inside fences as body text. Always place one line of prose before the code DurationIf there is a code fence beforeSTEP002。##the first non-empty line immediately afterDurationmust be#####The following headings cannot be used.#######limit to#There must be only one title. Before that is the metadata area, andkey: valuefails if any line other than this is placed- 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 is, if unspecified, 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 in a single document, so if left as is,repeated_sentence_leadfalse positives bury the real findings (measured 32 vs. 11). Since we 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, and.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 a correction instruction.Judge and record each one as either "fixed" or "leave (reason)." In procedure documents, the following judgments often come up.
- Such as "as follows~" and "~ is displayed"Keep fixed repetitions. In procedure documents, aligning sentence patterns reduces the reader's burden, so breaking them for variety makes it harder to read
- A sentence is long, contains two actions, or has distant dependenciesfix these. This directly connects to the principle in 4-1
- Translationese/prohibited words(such as "~ can be done" and "~ can be said") fix these. In procedure documents they are merely verbose and add no information
-
After fixing, the original
manual.mdreflect in, and.prose-check.mddelete.
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. How to read 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
- The parts left unverified (if any) and what you want confirmed
- The shooting request list (the one listed in 4-3)
If not requested, do not generate HTML or publish it.