@textlint-ja/textlint-rule-preset-ai-writing

The ai-tech-writing-guideline rule is based on the '7 Cs' of effective technical writing. These principles aim to create natural, readable, and professional technical documentation.

The 7 Cs of Technical Writing

• Clear (明確): No ambiguity; easy to understand.
• Concise (簡潔): Express necessary information with minimal words.
• Correct (正確): No errors in grammar, facts, or technical content.
• Coherent (一貫): Logically connected and flows smoothly.
• Concrete (具体的): Not abstract; measurable and clear.
• Complete (完全): Includes all necessary information.
• Courteous (丁寧): Appropriate tone and structure for the reader.

Core Principles for Implementation

1. Conciseness (簡潔性): Eliminate redundant expressions (e.g., replacing "まず最初に" with "まず").
2. Clarity (明確性): Use active voice and specific verbs instead of passive voice (e.g., replacing "処理が行われます" with "システムが処理します").
3. Concreteness (具体性): Replace abstract terms with measurable, quantitative data (e.g., replacing "高速なパフォーマンス" with "50ms未満の応答時間").
4. Consistency (一貫性): Unify terminology (e.g., choosing between "ユーザー" and "クライアント") and sentence endings (e.g., sticking to either "です・ます" or "だ・である").
5. Structure (構造化): Follow "one sentence, one idea" (一文一義), keep sentences under 50 characters where possible, and use lists/headings for logical organization.

You can configure options for each rule within the @textlint-ja/preset-ai-writing preset in your .textlintrc (or equivalent configuration file). Each rule has specific options to allow certain patterns or disable specific guidance categories.

Available rules that can be configured:

• no-ai-list-formatting
• no-ai-hype-expressions
• no-ai-emphasis-patterns
• no-ai-colon-continuation
• ai-tech-writing-guideline

{
    "rules": {
        "@textlint-ja/preset-ai-writing": {
            "no-ai-list-formatting": {
                "allows": ["許可したいテキスト", "/正規表現パターン/i"],
                "disableBoldListItems": false,
                "disableEmojiListItems": false
            },
            "no-ai-hype-expressions": {
                "allows": ["許可したいテキスト", "/正規表現パターン/"],
                "disableAbsolutenessPatterns": false,
                "disableAbstractPatterns": false,
                "disabledPredictivePatterns": false
            },
            "no-ai-emphasis-patterns": {
                "allows": ["許可したいテキスト", "/正規表現パターン/"],
                "disableEmojiEmphasisPatterns": false,
                "disableInfoPatterns": false,
                "disableHeadingEmphasisPatterns": false
            },
            "no-ai-colon-continuation": {
                "allows": ["許可したいテキスト", "/正規表現パターン/"],
                "disableCodeBlock": false,
                "disableList": false,
                "disableQuote": false,
                "disableTable": false
            },
            "ai-tech-writing-guideline": {
                "severity": "info",
                "allows": ["許可したいテキスト", "/正規表現パターン/"],
                "disableRedundancyGuidance": false,
                "disableVoiceGuidance": false,
                "disableClarityGuidance": false,
                "disableConsistencyGuidance": false,
                "disableStructureGuidance": false,
                "enableDocumentAnalysis": true
            }
        }
    }
}

Provides suggestions for improving document quality based on technical writing best practices, covering conciseness, clarity, specificity, consistency, and structure.

Options

• allows: A string or regex to allow specific patterns without reporting errors.
• severity: Set to "info" to treat findings as suggestions rather than errors.
• disableRedundancyGuidance: Set to true to disable redundancy detection.
• disableVoiceGuidance: Set to true to disable active/passive voice detection.
• disableClarityGuidance: Set to true to disable clarity detection.
• disableConsistencyGuidance: Set to true to disable consistency detection.
• disableStructureGuidance: Set to true to disable structure/organization detection.
• enableDocumentAnalysis: Set to true to enable analysis of the entire document.

Recommended Combination

It is recommended to use this alongside textlint-rule-preset-ja-technical-writing to fix definite errors while receiving additional improvement suggestions via severity: "info".

{
    "rules": {
        "preset-ja-technical-writing": true,
        "@textlint-ja/preset-ai-writing": {
            "ai-tech-writing-guideline": {
                "severity": "info"
            }
        }
    }
}