kf-g-writing-japanese-tech

Japanese writing standards

When writing or polishing Japanese that users will see (dialogue, technical documents, code comments, Markdown, etc.), follow the standards below.

Scope

Japanese dialogue with users (chat responses, explanations, confirmations)
Technical documents (book chapters, articles, explanatory text, guides, runbooks)
Code comments (comments that users read)
Other Japanese descriptions that users will see

Out of scope

AI agent internal thoughts, internal notes, drafts of delegation instructions
Intermediate artifacts not shown to users

How to read through

Short dialogue and comments: prioritize "rigor of argumentation", "prohibition of LLM-like expressions", "elimination of redundancy", and "viewpoint and narration"
Long technical documents: apply all sections in order. Apply book-oriented formatting, heading, and footnote rules according to the document format

Formatting

Insert a line break after each sentence. Indicate paragraph breaks with a blank line.
Show code, diffs, logs, and configuration file fragments in code blocks.
Supplementary notes that step slightly away from the main line, such as the origin of terms or the names of formalizations, should not be placed in the body text but moved down to footnotes ([^ラベル]).
Enumerations of definitions or classifications may be shown as bullet lists. Terms being defined should be bolded.
When defining or introducing a term for the first time in the body text, also bold that word. When referring to a term already introduced as a topic, quotations, or common names, use "" and distinguish it from bolding (first occurrence of a definition is bold, later mentions use "").
Dash (em dash —、horizontal bar ―, the so-called double dash "——") in Japanese prose or headings. For appositive or supplementary insertion ("A——insertion——B"), use parentheses (); for paraphrase or amplification ("A——B"), split into two sentences with a period or connect with a comma. An en dash indicating a range – or English compound words (Curry–Howard , etc.), code blocks, and bibliographic information are exempt.
Do not use the middle dot (・) in Japanese parallel constructions. However, it may be used inside a single proper noun.
Do not pack two elements such as "type──subject" or "subject──concept" into headings or column headings using divider lines (rule lines ─ U+2500 or dashes). Make headings a single natural phrase (narrow down to one element, or connect with particles or commas). Column headings should also not stop at a type name like "basics" or "supplement"; specify the content, as in "classification as an equivalence relation" or "loop invariants and induction".
For bullet lists that line up terms and their definitions, write "term：explanation" with a full-width colon rather than a divider line.

Structure of paragraphs and argumentation

Base this on paragraph writing. A paragraph is one step in an argument, and readers must be able to follow the logic paragraph by paragraph.

Put only one topic in one paragraph. A long paragraph that mixes multiple scene progressions (investigation, report, verification, evaluation) should be split into one-step paragraphs.
Make it so that reading the first sentence of a paragraph tells you what that paragraph is about.
At the beginning of a paragraph, explicitly indicate the logical relationship with the previous paragraph using connective expressions ("if so," "in fact," "however," "from this example itself too").
When introducing a new concept or term, do not suddenly begin with a dictionary-style assertion like "X is Y." First place the subject with an introductory sentence, then state its function and difference, and if necessary give the definition in the third sentence.
Advance the argument in one direction. Do not use a structure in which you state the conclusion, then handle counterarguments, and then restate the conclusion. After finishing handling counterarguments and doubts, place the conclusion only once.
Do not insert defenses of examples (such as preempting the impression that they are contrived) immediately after the climax of a scene and interrupt the flow. Handle them together at the beginning of the next section.
For misinterpretations the reader is likely to form, explicitly deny them before stating the real reason ("The reason is not 'because ~.' It is because ~.").
When negating by saying "not A but B," add one sentence giving the basis for the negation. A counterfactual ("if A, then it would have been ~") can often be used.
In concessions ("certainly ~"), limit yourself to confirming facts. If you assert as causation in the author's voice content that will be corrected later, it becomes self-contradictory. When you want to acknowledge a superficial diagnosis once, attribute it to the reader or to conventional opinion ("it might be possible to summarize it as ~").
Do not reveal in advance, in the paragraph just before, information you want to make effective at the climax (numerical values, specific facts).
When denying or limiting something, write out precisely in quotation marks the proposition being denied (for example, "does not mean 'if it is codified, everything can be entrusted to it'"). Do not settle for a vague denial such as "not everything will be solved."
Place forward references such as "will be dealt with in a later chapter" at a position where the argument has reached a pause (end of paragraph, end of section). Do not insert them in the middle of an argument and interrupt the flow.

Rigor of argumentation

Do not leave points in the logic of the text that invite objections. Once you have finished writing, preempt the reader's counterarguments and check the following points.

Do not mechanically change sentences written as conjecture, possibility, the reader's doubts, or counterfactuals into assertions. Cut "might be," "probably," "it seems," and "apparently" only when they weaken a claim without basis. When expressing unconfirmed possibility, a character's recognition, an inference from logs, a doubt the reader is likely to have, or a counterfactual, preserve that uncertainty. You may convert to an assertion only when the proposition is settled by evidence within the text. Bad example: change "might continue to present" to "continues to present." Good example: preserve the uncertainty and polish the sentence, as in "there is a possibility that it continues to present."
Do not lump different things together as "the same." Do not bundle together targets that should be distinguished (separate decisions, separate causes, problems of different kinds) under a single word. Bad example: writing that three interdependent pending matters "were making the same decision separately." Good example: dissecting it as "each was a separate decision, and moreover they depend on one another."
Do not reduce an event with multiple factors to a single cause. If an example contains multiple kinds of problems, separate each of them and map which tool explains which. Bad example: explaining an incident that mixes the absence of a contract with a failure of information hiding entirely as "a problem of information hiding."
Keep the treatment of the same concept consistent across chapters and sections. Do not classify something in one section as "humans decide" and write it in another section as "the team reaches agreement." Keep classifications, definitions, and the status of terms uniform throughout.
When asserting causality, state its mechanism (why it happens) in one sentence. Do not write only "if A, then B" and omit the reason. Bad example: "if you divide by procedure, changes ripple through the whole." Good example: "each process ends up sharing a representation for passing data, and changing that representation ripples through the whole."
Do not write as if detection, assurance, and resolution can "always" be done. State it accurately with conditions ("tends to be easy to," "can often be done," "only when ... holds").
For a claim, check whether the examples given actually support the whole of it. If the examples support only part of the claim, narrow the scope of the claim to match the examples.
For points deferred forward with "will be handled in the next section," confirm that they are actually picked up there. Do not plant foreshadowing that is never resolved.
Once you place a concession or qualification ("however," "even so"), always advance the argument afterward. Do not end on a contrastive turn and leave it hanging.
For a term central to a section, state its definition and scope before that section uses it. Do not start using it without defining it.
When grouping multiple concepts under a single superordinate term, immediately before naming it, state in one sentence that they come down to the same thing. Build a bridge to the reverse operation of dissection as well.

Managing the reader's load

Treat the reader's memory and attention as finite resources.

Do not introduce proper names (file names, function names, identifiers) that will not need to be referenced later. Get by with general expressions such as "the specification" or "the amount-calculation utility."
When what an abstract expression refers to cannot be uniquely determined from context, specify it on the spot with a parenthetical appositive whenever possible, and avoid making the reader reread earlier text as much as possible.
When adding a new example or scenario increases the context the reader must hold, preface it by explaining what differs from the previous example and why another one is needed, so the reader is convinced.
At the beginning of a chapter or in a section's introduction, do not cram in excessive detail unrelated to what the examples will cover.
Even within that section,omit only the excessive detailsthat are unrelated to that section's question or conclusion. Keep the specifics needed for the argument. Typical omissions are the decorative precision of agent reports (timestamps, HTTP statuses, coverage rates, etc.) and proper nouns that will not be referenced later.

Viewpoint and Narration

In examples, rather than listing results or using the passive voice ("was identified and determined"), write a series of actions with the agent as the subject ("investigated the repository, identified it, and found it").
Do not pointlessly prefix things with fictional character settings such as "a second-year engineer at the company."
Within the argument, do not address the reader as "you"; write with role names ("the developer," "the reader"). Second-person address should be confined to limited key points, such as introducing a scenario ("suppose that ...") or the conclusion of a chapter or book.
Choose words that refer to the object concretely. Do not blur it with broad words such as "AI" or "tool."
Once a formulation or term (K, contract, invariant, etc.) has been introduced in a chapter or section, use that word consistently thereafter. Do not retreat to vague words such as "context," "tool," or "AI" (using "context" etc. as an introductory word before formulating is fine).
For technical terms and translations, choose words customary in that field (e.g., push notifications are "delivery" [配信], not "shipping" [配送]). Do not substitute a Sino-Japanese word with a similar meaning based on the feel of an ordinary word.
When referring to a person themselves, write the original spelling (Lehman, Bainbridge). However, when introducing a historical figure or a concept named after a person by its established name, use the katakana common name accepted in Japanese.
Do not repurpose a word with the ring of a technical term in a nontechnical context (e.g., calling the chain from system to human a "path"). Write it in ordinary terms, such as "the flow until it arrives" or "what lies in between."
Do not write sentences that attach "です" to the terminal form of an i-adjective ("難しいです," "多いです"). This is not a rule of style but a sign that the flow of the sentence has broken down. The need to assert an i-adjective bare arises because that sentence is isolated from what comes before and after; in flowing prose, the sentence either continues as "〜は難しく、..." or is received with "〜でしょう" or "〜である." If one appears, do not patch only the sentence ending; rewrite the surrounding flow as well. The "〜です" of na-adjectives ("重要です") is outside the scope of this.

Restraint in Staging

The norm for staging is not an outright ban but a norm of moderation. Use rhetoric only where it produces an effect.

Use buildup ("here lies ...") or rhetorical questions to stage a derivation only at key points where tension serves the argument. Where explanation suffices, state it plainly.
Do not frequently create tension by making a short punch line its own paragraph. Short noun-ending phrases within a paragraph (e.g., "only a few dozen seconds so far.") may be used only at the climax of a scene.
Do not overuse bold emphasis in the text. Use it only at key points in the logic, such as negations that prevent misreading or the conclusions of clauses, and limit it to one or two places per section (the introduction is also acceptable). Otherwise, make things stand out through sentence order and structure.
Rather than imperative assertions such as "must not do X," choose forms written as the worker's judgment, such as "cannot very well do X."
Do not make turning points excessively dramatic. A single sentence stating the fact is often enough. Only at the climax of an argument is a short sentence with an exclamation mark acceptable.
Do not stir up accidents or danger by listing consequences.
Do not preview a claim with a preface such as "What is important is X." Write the claim as it is. However, prefaces that declare the style of the claim (such as "to put it another way as a slogan") may be used.
Do not overuse punchlines built on antithesis such as "it was not A but B." Light supplementary remarks or evaluations may be added in parentheses.
Do not use twisted idiomatic expressions (such as "put knowledge into the body") or metaphors whose referent is not uniquely determined (such as "a world spreads outside the report"). Say it directly with plain verbs ("become second nature," "fewer opportunities to notice").

Prohibition of LLM-like expressions

Do not be tempted by the empty templates that LLMs mass-produce. Once you have finished writing, check against this section. Using this book's terminology (essential complexity, recovery, placement of judgment, etc.) in an argument is fine. The problem is using it as empty decoration.

The following kinds of phrasing are LLM-speak that adds only a sense of "writing properly" without adding any points to the argument. Do not use them.

Previews and summaries: "What is important is X," "This chapter deals with/explores X," "Here we will look at X," "In summary," "In short" (when it is only a restatement of what immediately precedes), "is nothing other than X"
The frontal-approach family: "deal with head-on," "recover head-on," "look at/write about/set up head-on"—declaring only the attitude in place of substance
Empty adjectives: "indispensable," "central," "key," "fundamental" (emphasizing without explaining the substance of the claim), "multifaceted," "comprehensive," "holistic" (not writing what was looked at and how)
Empty verbs: "dig deeper," "delve deeper," "put into words" (ending without showing what was written and how), "touch on," "mention" (merely finishing with a single paragraph)
Connection templates: "in X," "from the aspect of X," "from the viewpoint of X" (no new information), repeated use of "furthermore," "also," "in addition"
Weak hedging and praise: "one could say that X," "X may be" (only when weakening a claim without grounds. Keep them if they are conjecture, supposition, the reader's doubt, or a character's perception), "very," "extremely," "greatly" (empty emphasis)

Bad example: "This chapter deals head-on with the theory of XX," "I will here take up this premise head-on," "When analyzed from multiple angles, what matters is ~." Good example: "This chapter deals with the theory of XX," "Here, I take up this premise," "The core of the evaluation lies in who knows what is correct."

Eliminating redundancy

Leave as little wasted text as possible.

Do not repeat the same claim in different words. Write one claim only once.
If adjacent sections state the same thing from a different angle, their roles overlap. Absorb one into the other and combine them into a single section.
Immediately after describing a scene, do not re-summarize its content. Place only a single sentence of significance (such as "This kind of work can be left almost entirely to it").
For parallel facts that have the same logical role, do not stack them in separate sentences; combine them into one sentence. Indicate the logical status of that group of facts with the opening word (e.g., "Naturally, both the accounting department's monthly processing and customer payments ~").
Do not write explanations of intermediate steps that readers can fill in themselves.
If an argument spanning several sentences can be compressed into one sentence, leave only the compressed sentence. You may use "in short" as a signal of summary.
Do not place sentences that exist only for connection or evaluation (such as "that in itself is a good thing").
Do not use imagined dialogue with the reader (such as posing a question and answering it in one word) as rhetoric. State claims directly. Likewise avoid the form of acting out and responding to the reader's reaction (e.g., "You may have felt ~. That is exactly right"), and make concessions briefly in the main text (e.g., "Of course, the treatment itself is not a matter for the developer to decide").
Do not introduce ideas the reader is likely to have through meta-framing (e.g., "There is a natural continuation to the discussion so far," "This is the idea that ~"). Write the idea itself directly. If it is the reader's question, it may be written as a question (e.g., "Why not leave that maintenance to it as well?").
Do not write defenses or disclaimers of the author's position, such as "This book does not deny that either." Place only factual statements (e.g., "In many cases, ~ is made to write it").
Make the text share the context with the reader in the shortest way possible. If it can be conveyed without unfolding the derivation step by step, give the structure a name and state it outright.
Do not bring up concepts or document names not yet introduced in the main text ahead of time.
Do not settle for hesitant, weak predicates (such as "is an effective measure"). State strongly and concretely what is established by the evidence in the main text (such as "is indispensable in utilization"). However, retain weak predicates for expressing uncertainty, possibility, assumptions, or the reader's doubts. Intentional softening for tone (such as "one could say it is indispensable") is permitted.
Connective expressions used to create rhythm in the text (such as "but on the other hand") are not considered redundant.

How to attach headings

Make headings specific enough to identify the content. Use a phrase that refers to the question the section answers or the subject it deals with.

Do not use headings that merely state the steps of a task (such as "Return to the example" or "Reread ~"), or headings that carry no information. Make the heading refer to the question the section answers or the subject it deals with.
Do not turn the heading into a "punchline" that states the section's conclusion outright. Avoid a state in which the reader knows the payoff at the point of the heading.
A noun phrase referring to the subject dealt with in the section is also acceptable.
It does not matter whether the heading is interrogative or declarative. What matters is whether it refers to the subject being dealt with or to a question the reader has.
Choose whichever fits the tone of the body text: an interrogative form or a noun phrase referring to the subject.

Honesty toward the reader

If an example may look contrived, do not hide it. Acknowledge the reader's doubt in advance and briefly add grounds for it being sufficiently plausible in reality.
Those grounds should not rest on the author's assertion ("this is a sufficiently plausible situation") but on general facts or common beliefs that appeal to the reader's own experience ("this symptom is not rare, is it?", "you often hear the phrasing ~ too").
Do not write smoothly about things you have not verified as if you had verified them.