From the materials, manual.md is written up, and this covers through passing lint and turning it into HTML. The reader is assumed to be "a junior high school student who knows nothing at all about the field." Success is when the reader can reach the end without stopping along the way; anything else is considered failure.
Overall flow
素材 → 執筆(§1-4) → 日本語チェック(§5) → lint(§6) → HTML 生成(§7) → 報告(§8)
↑ │
└───── 本文を書き足す必要が出たら ──┘
There is a reason for each of the steps not being reordered.
- Japanese checks come before lint. Fixing the Japanese can shift lines, and the relative paths of images or the
Durationpositions can break. If done in the reverse order, lint that should have passed will fail again - Run lint standalone before build.
buildstops when it fails lint, so it is better to look at all the diagnostics first and fix them together to reduce back-and-forth
You do not necessarily start the process from the beginning. Look at what you have on hand and choose the entry point.
| What you have on hand | Entry point |
|---|---|
| Only materials (source, README, notes, URLs) | From §1 |
.md exists (including work in progress) |
First grasp the current state with lint in §6. After seeing the diagnostics, decide whether fixes are enough or a rewrite is needed |
.md exists and lint passes |
Generate HTML in §7 |
| HTML already exists but you want to fix the content | What you fix is .md. Do not touch the generated output (→ §9) |
If you do not know, check whether .md exists, and if it does, run lint once. Diagnostics are the cheapest and most informative way to grasp the current state.
1. Read the materials
If the target directory or materials are not indicated, ask first. Once indicated, read README, entry points, configuration files, existing documentation, and task definitions such aspackage.json with priority.
There is only one thing to decide here.What facts may be written in this procedure document。
- Write only the commands, paths, versions, and outputs that can be confirmed from the materials
- Do not write things that cannot be confirmed. If you want to write them, ask the user or explicitly mark them as "(unconfirmed)" and leave them 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 materials are 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 procedure (equipment, accounts, installed items)
Do not mix prerequisites and procedure. "Prerequisites" are what the reader prepares in advance; "procedure" is what is done within this document. If they are mixed, the reader will not know where they are.
3. Break into steps
1 step = 1 verifiable change of state. This is the only criterion for how to break things down.
The reader can stop 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." A unit for which that cannot be written is too large or too small as a step.
- Too large example: "Set up the environment" (it is unclear how far you must go for success)
- Just right example: "Install Go and verify that
go versionis displayed" - Too small example: "Open the terminal" (there is no state change to verify by itself)
The first step must always be "confirmation of the goal and prerequisites." The reader begins reading while anxious about whether they have opened the correct document, so resolve that first. The last step should be "confirmation of what was accomplished" and contact information.
Duration is used to check whether the breakdown is correct. If a step exceeds 15 minutes, it usually contains two or more changes of state. Estimate the actual time honestly, and do not fill it with round values such as0:05:00 .
4. Write
The template is assets/template.md. It passes lint as is, so copy it to the output destination and then replace the contents.id: replace-me and each heading and body text must be rewritten (do not leave the explanatory text as is).environments は Web、status is, unless specified, Draft may remain as is.
For input conventions, the diagnostic table in §6 is the only ledger. If you are unsure while writing, look there. The following three are especially easy to stumble on, so keep at least these in mind before writing.
DurationはH:M:SSrequires the 3 delimiters (5:00will fail. Write0:05:00)##The first non-empty line immediately afterDuration. Do not place a code fence first- If the body of a step is only a code block, it will fail. Always place one line of prose before the code
4-1. Conditions for sentences that a junior high school student can understand
The cause of readers getting stuck is not vocabulary, butcontext omitted by the writer. Follow the rules below.
| Principle | Reason |
|---|---|
| One action per sentence | If you write two, the reader is forced to decide which to do first |
| Write "where" first | "In the terminal, run the following." If the reader reads the verb without knowing the place, their hands stop |
| Paraphrase technical terms at the point of first appearance | 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 to things by name | Write button names and file names on the screen exactly as they appear |
| Use polite form (desu/masu) consistently | If it drops into plain form partway through, it reads as if someone else wrote it |
4-2. When to include code
There is only one criterion.Is it something the reader must reproduce exactly as written. Put things to reproduce in code blocks, and write explanations in prose.
| Purpose | How to write it |
|---|---|
| Commands to execute | ```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 the language name, as in . State the file path in the prose immediately before it |
| Output expected to appear on screen | ```text. This is for readers to compare against, so include the actual string that appeared exactly as it was |
| 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 the 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 confirmed from the source material are dangerous precisely because they can be written plausibly, and readers get stuck there.
4-3. When to include images and screenshots
Images have only two jobs.To show "which one to press"と、To let readers verify "is this correct". Do not include anything other than these two.
Include
- When the GUI target of an operation cannot be identified by name alone (icon-only buttons, multiple items with the same name)
- When you want readers to compare against the "correct appearance" (for example, whether the settings screen has opened correctly)
- When you want to show the relationship between steps first (→ however, this is often sufficient with a
```textdiagram)
Do not include
- Commands, paths, setting values, error messages. If made into images, they cannot be copied and will not be found by search. This harms readers
- 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
- Save location is
manual.mdat the same level asimages/. References are relative paths - In alt text, write not "what is shown" butwhat you want the reader to check.
rather than
When the image does not exist yet, do not write its path. lint checks that relative images actually exist, so writing a path you intend to add later will stop the build. Instead, present aphoto request listto the user separately from the document.
撮影をお願いしたい画面（撮れたら 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 them helps the reader, but a procedure document still works without them.
Note box. in the claat parser README at Positive と : 本文 The two-line form ofdoes not work in the claat version this workflow pins。<p>Positive : 本文</p> and becomes a plain paragraph. Use one 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 underEnglish heading string itselfare rendered as a checklist. However, this determination is made against the### 学ぶこと . If you want to use it in a Japanese procedure document, only the heading would need to be in English, but ordinary bullet points convey it well enough for the reader. Judge by the content whether it is worth making the heading English.
Tables, links, and lists are as in ordinary Markdown.
5. Japanese check (always before lint)
The Japanese you have written usually contains "repetition of the same template" and "translation-like phrasing". You cannot notice this yourself, so have a machine detect it.
-
Duration:Create a copy with lines replaced by blank lines.Duration:appears dozens of times per document, so as-is,repeated_sentence_leadfalse positives bury the real findings (measured 32 versus 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 and target.prose-check.md. 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.Decide and record, one by one, whether to "fix" or "keep (reason)". In procedure documents, the following judgments come up often.
- Keepfixed repetitions such as "as follows" and "is displayed". In procedure documents, aligning sentence patterns reduces the reader's burden, so breaking them for variety makes them harder to read
- A sentence is long, contains two actions, or has a distant dependencyFix it. This directly ties into the 4-1 principle
- Translationese / forbidden words(“can do 〜”, “one could say that 〜”) Fix these. In a procedure manual they are merely verbose and add no information
-
Once fixed, reflect it in the original
manual.md, and.prose-check.mddelete the .
6. Pass lint
The lint binary cmd/claat-tools/main.go is bundled with this skill.Since it is a relative path from the same directory as this SKILL.md, replace it at runtime with the absolute path of the skill directory. It depends only on the standard library and go.mod is not needed either, sothe working directory can be anywhere(it works even if the user's project is a separate module). From the second run onward, Go's build cache takes effect.
go run <skill>/cmd/claat-tools/main.go lint path/to/manual.md
Fix until the exit code is 0.
| code | Meaning | What to do next |
|---|---|---|
| 0 | Success | Proceed to §7 |
| 1 | Input lint error | Read the diagnostic and fix it (below) |
| 2 | Execution environment problem | claat is not in PATH, the argument is invalid, the file cannot be read, or it is not UTF-8 |
| Other | claat itself failed |
claat Read 's standard error output as is |
Do not confuse 1 and 2. 1 is about fixing the document, and 2 is about fixing the environment.
However, go run via , the shell receives $? はOn failure it is always 1(because Go outputs the original exit code to standard error as exit status N and itself exits with 1).$? Do not branch on , but read the last line of standard error to decide.claat was not found in PATH As in , in case 2 the message explicitly states that it is about the environment.
Diagnostics are output to standard error in the form path:line:column: error CODE message .
dev/manual.md:12:1: error STEP002 expected `Duration: H:M:SS` immediately after the step heading
dev/manual.md:48:5: error ASSET001 local image not found: images/setup.png
Principle for fixing: do not delete content just to silence lint. ASSET001 To delete , removing the ![...]() line is the easiest and most damaging fix. The reader needed that image, which is why it was placed there. The error is an instruction to “prepare an image,” not to “stop referencing it.”
| code | Meaning | Judgment |
|---|---|---|
META001 |
Required metadata is missing | Fill in only the values that can be determined (status は Draft）。summary feedback link analytics account Do not decide on your own; ask |
META002 |
Unknown key or duplicate key | Fix it. Only the 7 keys (summary id categories environments status feedback link analytics account) can be used.tags や authors Adding will fail here. For duplicates, before deleting one, confirm which value to keep |
META003 |
Invalid value | Fix it.id は [A-Za-z0-9][A-Za-z0-9_-]*(neither Japanese nor slashes can be used),environments は Web / Kiosk、status は Draft / Published / Deprecated / Hidden |
DOC001 |
# No title / multiple titles / invalid position |
Fix it.# must be only one, and no lines other than the metadata area (key: value can be placed before it). The second and subsequent # is usually ## are typos, so demote them. However, demoting adds one step, so report the corrected content |
STEP001 |
## is missing, or the heading level is invalid |
Fix it.##### ###### は #### promote it to |
STEP002 |
Duration is missing / position is invalid / format is invalid |
Fix it.H:M:SS requires 3 delimiters, and 5:00 does not pass.## place it on the first non-empty line immediately after. (Do not place a code fence first.) For steps without a value, estimate the required time from the content, propose it, and confirm |
STEP003 |
The step body is empty | Return it to the writer. However, if the body consists only of a code block, this is by lint specification (content inside fences is not counted as body), and it can be fixed by adding one line of prose before the code |
MD001 |
Code fence is not closed | Fix it. Determine where it should be closed from the surrounding context. The starting line appears in the diagnostic, so read from there |
ASSET001 |
Relative image does not exist | Do not remove the reference. If it is a misspelling of the path, fix it. If the file itself does not exist, ask the user, including which screen to capture and where in images/ they want it placed |
If it becomes necessary to add a large amount of body text, that becomes writing work rather than conversion. Return to §4, also pass the Japanese check in §5, and then return to §6.
7. Generate HTML
HTML conversion itself is delegated to claat on PATH.This is the only thing that needs to be installed.
claat version
If it is not present, install the verified version.
go install github.com/googlecodelabs/tools/claat@v0.0.0-20240220115335-873fe39d02dc
If lint passes, generate it.
go run <skill>/cmd/claat-tools/main.go build -output output path/to/manual.md
build internally runs the same lint first. On success, it outputs claat が ok<TAB><id> , and the output is created with a name using the metadata id .
output/
└── <id>/
├── index.html
└── codelab.json
The default output destination is output。-output(short -o) can be changed.Existing files are not deletedso,id If you change and regenerate, the old directory remains. If it is unnecessary, deleting it is the responsibility of the person who ran it.
After generation, confirm that index.html has actually been created before reporting. Even if lint passes, if claat fails on its side, the exit code will be that of claat . If you want to check the appearance locally, claat serve can be used.
8. Report
Completion requires the following three things. If even one is missing, do not say "done."
- lint exits with code 0
output/<id>/index.htmlexists (if HTML is also requested)- The remaining homework is communicated to the user as a list
3 is especially easy to drop. Convey the following without omission.
- Generated
index.htmlとmanual.mdpath of - Places fixed by lint (what was fixed and why)
- Images not yet captured (which screens, and in which path you want them placed)
- Descriptions left as "unverified" because they could not be confirmed from the materials
- Metadata that only the user could decide (
summarywording,feedback link、analytics account）
Unless asked, neither commit nor publish the generated artifacts.
9. Principles of proceeding
Do not edit generated artifacts. output/<id>/index.html is regenerated every time. Even if you fix it here, it disappears in the next build, and.md the content will remain inconsistent with the HTML without anyone noticing.The thing to fix is always .md , and the HTML should only be opened for checking.id When is changed, ask the user whether to delete the old output directory.
Do not stop at images. Rather than halting the entire process until images are complete, first run through all the parts that do not require images..md Once you have finished writing , passed the Japanese check, and eliminated all lint errors other than images, hand it to the user with a list of photography requests. Leave it in a state where, once the images arrive, all you need to do is run lint and build.
Send-backs should be at most 2 round trips for the same document. If you enter the 3rd round trip, the cause is usually not the document but something else. The materials are insufficient,claat 's environment is broken, or the procedure you are trying to write is not settled in the first place—one of these is often the case. If the same diagnostic code appears twice in a row, treat it the same way; rather than repeating the count, it is faster to return to the user what is not understood.