Japanese Text
Conventions for writing Japanese text across multiple contexts. These guidelines reflect the author's personal style derived from blog posts and articles. Context-specific conventions always take priority.
Writing Contexts & Register
Identify the context before writing. Each has a distinct register:
- Personal diary/journal (diary.sorah.jp, journal/general posts): casual だ/である調, highly opinionated, personal reflections, stream-of-consciousness allowed
- Technical articles (diary.sorah.jp tech posts, or technical reports): structured but opinionated, plain form (だ/である調), precise terminology, explanatory. Note: blog.sorah.jp is used for English articles; Japanese technical writing goes on diary.sorah.jp
- Corporate/external blog (techlife.cookpad.com etc.): です/ます調, structured, educational, more formal tone while remaining approachable
When the context is ambiguous, ask which register to use.
Orthography & Formatting
- Half-width space between Japanese and Latin script:
Ruby を使う, API の設計
- Half-width space between Japanese and numbers:
2025 年, 3 つ
- Half-width Arabic numerals for all numbers
- Half-width parentheses
()
- Japanese punctuation:
、 (comma) and 。 (period), full-width
- Backticks for code, commands, and technical terms inline:
`bundle exec`, `Enumerable`
- Technical terms kept in English when commonly used that way in the Japanese tech community
<!--more--> for article break (fold marker)--- (horizontal rule) as section divider when shifting topic within a post- Markdown for links and formatting
- Self-reference: わたし (hiragana), not 私 (kanji)
Vocabulary & Expression Preferences
Natural, colloquial expressions are preferred over stiff formal language:
- Casual vocabulary: だるい, シュッと, ちまちま, しょうがない, ちりつも, べんり, つらい, えらい
- Hedging: おそらく, たぶん, 〜な気がする, 〜と思う, 〜っぽい
- Sentence-ending particles (casual contexts): ね, な, なぁ, し, けど, よね
- Strong opinions expressed directly — don't soften harsh assessments of bad technology or design decisions
- Self-deprecating and honest about one's own limitations or laziness
Sentence Structure
- Parenthetical asides in
() for tangential but relevant notes
- Footnotes
[^label] for extended asides or references
- Connectors: そして, その上で, また, 一方で, ただ, ただし, あとは, ちなみに, というか
- Trailing off with
… or …… for hesitation or unfinished thoughts
- Long compound sentences connected with て-form, が, けど, し are natural — don't force short sentences
- Guard-clause style: state the conclusion or opinion first, then explain the reasoning
- Avoid repeating the same phrase or sentence-ending suffix across consecutive sentences — vary sentence endings (〜した, 〜だった, 〜ている, 〜だろう, etc.) to maintain rhythm
Paragraph & Composition
Technical posts
Background/motivation → approach → implementation details → learnings/outro. Use ## headers for major sections.
## tl;dr section near the top for a quick summary before detailed explanation- Paragraphs can be long when explaining technical details
- Short paragraphs for opinions and feelings
- Closing section header: "Outro" (used in Japanese posts too), "おわり", or "おわりに"
- Dedicated criticism subsections when warranted (e.g., "AWS 悪口コーナー") — don't bury strong negative assessments
Diary posts
Section-based structure organized by topic (仕事, コミュニティ, 趣味, 買ったもの, etc.) with ## headers.
- Yearly or periodic roundups follow a chronological or thematic structure
- Personal opinions and feelings are the primary content
Corporate blog posts
Introduction → problem/background → solution/approach → results/learnings → conclusion. More structured than personal posts.
Links, References & Media
- Links woven naturally into prose as inline Markdown links, not listed separately
- Include GitHub repository links, Speaker Deck presentation links where relevant
- Product names with exact model numbers when discussing hardware/purchases
- Affiliate links disclosed with
<small>Disclaimer: ...</small>
Formatting Constraints
- Avoid bullet points in article prose — write in flowing paragraphs instead. Bullet lists are acceptable only for structured enumerations (spec lists, event lists, changelog items)
- Avoid
**bold** in article prose — use backticks for technical terms, or restructure the sentence to make emphasis natural
- These constraints apply to the article body; this skill document itself uses bullets for reference convenience
What NOT to Do
- Don't over-explain things that are obvious to the target audience
- Don't use overly formal or stiff language in diary/personal context
- Don't shy away from strong opinions — state them clearly
- Don't sanitize personal feelings about technology decisions
- Don't add unnecessary politeness hedging in technical explanations (casual/technical contexts)
- Don't force unnaturally short sentences — Japanese prose naturally uses longer compound sentences
- Don't repeat the same words or phrases — rephrase to avoid monotony