Fix documentation quality issues in legacy docs (Desktop-legacy, Develop-legacy, language-legacy) - #2
Conversation
- Fix misspelled link slugs: sempahore → semaphore, clear-sempahore → clear-semaphore - Fix truncated link slug: ction-info → action-info - Fix truncated link slug: set-quer-destination → set-query-destination - Fix typo in code comment: modfiy → modify - Fix malformed admonition syntax: ::info → :::info - Replace French word 'encodage' with proper English in XML example Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
- Fix SAX acronym: 'Simple API XML' → 'Simple API for XML' - Fix org name: 'Apache Foundation company' → 'Apache Software Foundation' - Fix XSL definition: 'contents of an XSL document' → 'contents of an XML document' - Fix tab character and missing space in Markdown table - Remove orphan admonition wrappers around plain text paragraphs - Fix awkward phrasing: 'provoke errors' → 'cause errors' Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The subtraction operator was lost during HTML-to-Markdown export. Original confirmed at library.4d-japan.com/doc/4Dv20. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Session Usage Summary
The high input token count is due to reading large file outputs repeatedly across multiple tool calls, with the growing context window accumulating ~110K tokens by the final turns. Can this be delegated to a cheaper model?Yes — with caveats. Here's my assessment: What the task involved:
Delegation recommendation:
Recommended approach for future runs:Two-phase workflow:
Phase 2 alone would cost roughly 1/10th of this session since it's pure mechanical search/replace with no discovery needed. A model like |
Documentation Quality Audit — Instruction File for LLM AgentsPurposeThis document provides comprehensive instructions for an LLM agent to repeat a documentation quality audit on the Repository Context
Scope DefinitionTarget directoriesWhere File typesOnly Content language mix
Important: ALL directories contain Japanese content that must be audited. The English-only content is limited to a few Develop-legacy files (records.md, sets.md, xml.md, transactions.md, legacy-to-import.md). Key Understanding: Version CopiesThe versioned directories ( To verify: diff path/to/current/file.md path/to/version-21-R4/file.mdThe only differences between versions are typically:
What to Look ForCategory 1: Broken Links (Highest Priority)The HTML-to-Markdown export introduced typos in link slugs. These result in 404 pages. Detection method: # Search for suspicious link patterns — misspelled command names
grep -rn "../commands/[a-z-]*" --include="*.md" <target_dirs> | \
sort -u | # check for obvious typos in slugsKnown patterns from previous audit:
Verification: Cross-reference link targets against actual file slugs in the Category 2: Typos in Code CommentsCode examples contain English comments that may have typos: grep -rn "//" --include="*.md" <target_dirs> | grep -i "modfiy\|recieve\|occured"Category 3: Markdown Syntax ErrorsAdmonition syntax (Docusaurus-specific):
Detection: # Find malformed openers (only 2 colons)
grep -rn "^::info\|^::note\|^::tip\|^::caution\|^::warning" --include="*.md" <target_dirs>
# Find orphan closers
grep -rn "^:::" --include="*.md" <file> | # count — should be evenCategory 4: French Language RemnantsThe 4D documentation originates from a French company (4D SAS). The original source is French, translated to English, then to Japanese. French words occasionally survive in the English text. Detection: grep -rn "encodage\|paramètre\|résultat\|fichier\|fonction" --include="*.md" <target_dirs>Known instance: Category 5: Prose Quality (English Develop-legacy files)These files contain full English paragraphs. Look for:
Category 6: Formatting Issues
Category 7: Spelling Inconsistency
What NOT to FlagCritical to avoid false positives:
Execution StrategyPhase 1: Discovery (Read-only)
Phase 2: FixesApply fixes in this priority order:
For each fix:
Phase 3: Commit & PR
Verification ResourcesArchived original documentation
Command slug verification
Common Pitfalls & Caveats
Sample grep Commands for Comprehensive AuditROOT="i18n/ja/docusaurus-plugin-content-docs"
DIRS="$ROOT/*/Desktop-legacy $ROOT/*/Develop-legacy $ROOT/*/language-legacy"
# Broken links - misspelled slugs
grep -rn "../commands/[a-z-]*" --include="*.md" $DIRS 2>/dev/null | grep -i "sempah\|ction-\|quer-d"
# Duplicate words
grep -rn "the the\|to to\|is is\|in in\|of of\|and and" --include="*.md" $DIRS
# French remnants
grep -rn "encodage\|paramètre\|résultat\|fichier" --include="*.md" $DIRS
# Malformed admonitions
grep -rn "^::info\|^::note\|^::tip\|^::warning\|^::caution" --include="*.md" $DIRS
# Common misspellings
grep -rn "occured\|occurence\|seperator\|seperate\|modfiy\|recieve" --include="*.md" $DIRS
# Tab characters in tables
grep -rn "$(printf '\t')" --include="*.md" $DIRS
# Spelling inconsistency
grep -rn "cancelled\|canceled" --include="*.md" $DIRSOutput FormatThe audit report should follow this structure:
Every finding MUST include:
Estimated Effort
Model Selection Guidance
The judgment-heavy parts (distinguishing real errors from false positives in mixed-language content, recognizing French remnants, identifying factual inaccuracies) require a stronger model. The mechanical fix application can be delegated to a cheaper model with explicit instructions. |
1 participant
Documentation Quality Audit Report
Summary
Desktop-legacy/,Develop-legacy/, andlanguage-legacy/directories in 4+ version trees (current,version-21,version-21-R3,version-21-R4)Status: ✅ ALL FIXES APPLIED
All findings below have been fixed and committed. PR #2 contains all changes.
Commits (in order)
Findings — English (All Fixed ✅)
1. Typos / Spelling
i18n/ja/docusaurus-plugin-content-docs/current/Develop-legacy/records.md(line 248)Context:
Problem: 🔴
modfiyis a misspelling ofmodify.Suggested correction:
i18n/ja/docusaurus-plugin-content-docs/current/Develop-legacy/legacy-to-import.md(lines 34, 36, 51, 67)Context:
Problem: 🔴 The link slugs
sempahoreandclear-sempahoreare misspelled. The correct spelling issemaphore/clear-semaphore.Suggested correction:
i18n/ja/docusaurus-plugin-content-docs/current/Desktop-legacy/standard-actions.md(line 17)Context:
Problem: 🔴 The link slug
ction-infois missing the leading "a" — should beaction-info.Suggested correction:
i18n/ja/docusaurus-plugin-content-docs/current/Develop-legacy/records.md(line 134)Context:
Problem: 🔴 The link slug
set-quer-destinationis missing a "y" — should beset-query-destination.Suggested correction:
i18n/ja/docusaurus-plugin-content-docs/current/Develop-legacy/xml.md(line 15)Context:
Problem: 🟠 SAX stands for "Simple API for XML". The word "for" is missing.
Suggested correction:
i18n/ja/docusaurus-plugin-content-docs/current/Develop-legacy/xml.md(line 27)Context:
Problem: 🟠 The correct name is "Apache Software Foundation", not "Apache Foundation company". Also, "company" is inappropriate — it's a non-profit foundation.
Suggested correction:
2. Grammar
No pure grammar errors found in the English prose beyond those covered elsewhere.
3. Punctuation / Spacing / Markdown Syntax
i18n/ja/docusaurus-plugin-content-docs/current/Develop-legacy/sets.md(line 138)Context:
Problem: 🔴 Docusaurus admonition syntax requires three colons (
:::). This line has only two colons, so the admonition will not render correctly.Suggested correction:
i18n/ja/docusaurus-plugin-content-docs/current/Develop-legacy/records.md(line 34)Context:
Problem: 🟡 The closing admonition marker
:::has a trailing space (:::). While most parsers tolerate this, it's inconsistent with the rest of the file. Needs verification that this renders correctly.i18n/ja/docusaurus-plugin-content-docs/current/Develop-legacy/sets.md(line 41)Context:
(where ⇥ is a tab character)
Problem: 🟠 There is a tab character between "of" and "selected" inside a Markdown table cell. This may render unexpectedly and is likely a data-entry artifact.
Suggested correction:
Also note the missing space before
(in bytes).i18n/ja/docusaurus-plugin-content-docs/current/Develop-legacy/records.md(lines 214–220)Context (reconstructed):
Problem: 🟠 The two
:::pairs at lines 216/220 create empty unnamed admonition blocks wrapping regular paragraph text. This text should either be outside any admonition (remove the wrapping:::), or the admonition type was accidentally omitted (e.g.,:::tip).Suggested correction: Remove the orphan
:::at lines 216 and 220, leaving the text as regular paragraphs.4. Duplicate Words
No duplicate-word issues (
the the,to to, etc.) were found in the English prose.5. Bad / Awkward Prose
i18n/ja/docusaurus-plugin-content-docs/current/Develop-legacy/xml.md(line 17)Context:
Problem: 🟠 "provoke errors" is translated-sounding. Standard English technical writing would use "cause errors" or "result in errors".
Suggested correction:
i18n/ja/docusaurus-plugin-content-docs/current/Develop-legacy/xml.md(line 66)Context:
Problem: 🟠 "Computerized data exchange standard" is awkward and translated-sounding. It's more naturally described as a "markup language" or "data interchange format".
Suggested correction:
i18n/ja/docusaurus-plugin-content-docs/current/Develop-legacy/xml.md(line 67)Context:
Problem: 🟠 "contents of an XSL document" is factually misleading — XSL stylesheets process XML documents, not "XSL documents".
Suggested correction:
i18n/ja/docusaurus-plugin-content-docs/current/Develop-legacy/records.md(line 246)Context:
Problem: 🟡 This code example appears to be missing an arithmetic operator. It likely should be
[Inventory]Part Qty - 1or[Inventory]Part Qty + 1. Needs verification against the intended logic (likely subtracting inventory).Suggested correction:
6. Terminology / Consistency
i18n/ja/docusaurus-plugin-content-docs/current/Develop-legacy/transactions.mdContext (multiple lines):
Problem: 🟡 The file mixes US spelling
canceled(lines 10, 12, 83, 197) with UK spellingcancelled(lines 14, 143, 205, and also records.md line 210). The same word appears in both forms within the same file.Action: Choose one spelling consistently. Since US English uses
canceledand the majority of occurrences in the files use that form, standardize tocanceledthroughout. Alternatively, if UK English is the house style, change all tocancelled.7. Contradictions
No definite contradictions were found between files.
8. Repeated / Shared Errors
All issues listed above are repeated across version directories. The
current/andversion-21-R4/copies are byte-identical for affected files. Theversion-21-R3/andversion-21/directories contain subsets of the same content with only link-path format differences.sempahore/clear-sempahoretypo in link slugsAffected files:
i18n/ja/docusaurus-plugin-content-docs/current/Develop-legacy/legacy-to-import.md(lines 34, 36, 51, 67)i18n/ja/docusaurus-plugin-content-docs/version-21-R4/Develop-legacy/legacy-to-import.md(lines 34, 36, 51, 67)Global fix: Search/replace
../commands/sempahore→../commands/semaphoreand../commands/clear-sempahore→../commands/clear-semaphorection-infotypo in link slugAffected files:
i18n/ja/docusaurus-plugin-content-docs/current/Desktop-legacy/standard-actions.md(line 17)i18n/ja/docusaurus-plugin-content-docs/version-21-R4/Desktop-legacy/standard-actions.md(line 17)Global fix: Search/replace
../commands/ction-info→../commands/action-infoset-quer-destinationtypo in link slugAffected files:
i18n/ja/docusaurus-plugin-content-docs/current/Develop-legacy/records.md(line 134, 2 occurrences)i18n/ja/docusaurus-plugin-content-docs/version-21-R4/Develop-legacy/records.md(line 134, 2 occurrences)Global fix: Search/replace
../commands/set-quer-destination→../commands/set-query-destinationmodfiytypo in code commentAffected files:
i18n/ja/docusaurus-plugin-content-docs/current/Develop-legacy/records.md(line 248)i18n/ja/docusaurus-plugin-content-docs/version-21-R4/Develop-legacy/records.md(line 248)::info(missing colon) admonition syntaxAffected files:
i18n/ja/docusaurus-plugin-content-docs/current/Develop-legacy/sets.md(line 138)i18n/ja/docusaurus-plugin-content-docs/version-21-R4/Develop-legacy/sets.md(line 138)French word
encodagein English XML exampleAffected files:
i18n/ja/docusaurus-plugin-content-docs/current/Develop-legacy/xml.md(line 136)i18n/ja/docusaurus-plugin-content-docs/version-21-R4/Develop-legacy/xml.md(line 136)Context:
Problem: 🔴
encodageis a French word meaning "encoding". It is a leftover from the original French documentation.Suggested correction:
Or use a placeholder like
{encoding}orUTF-8.Tab character in Markdown table
Affected files:
i18n/ja/docusaurus-plugin-content-docs/current/Develop-legacy/sets.md(line 41)i18n/ja/docusaurus-plugin-content-docs/version-21-R4/Develop-legacy/sets.md(line 41)14. Obvious Remnants of Another Language
i18n/ja/docusaurus-plugin-content-docs/current/Develop-legacy/xml.md(line 136)🔴
encodageis French for "encoding". This is an obvious French remnant in what is otherwise English documentation.Findings — Japanese (All Fixed ✅)
9. Wrong Katakana Character (53 files)
Problem:
フィ－ルドuses U+FF0D (FULLWIDTH HYPHEN-MINUS －) instead of U+30FC (KATAKANA PROLONGED SOUND MARK ー). This is invisible to casual readers but is technically incorrect and would break text search for フィールド.Fix applied:
フィ－ルド→フィールドglobally across 53 files.Affected directories:
*/language-legacy/On a Series/*.md(7 commands × 3 versions = 21 files)*/language-legacy/Data Entry/reject.md(×3 versions)*/language-legacy/Printing/print-form.md(×3 versions)*/language-legacy/Sets/save-set.md(×3 versions)*/FormObjects/properties_Display.md(×6 versions)version-21/commands-legacy/*.md(10 files)version-21/commands/print-form.md10. Inconsistent Terminology: トリガ vs トリガー
*/Develop-legacy/triggers.md(×3 versions)Context examples:
トリガをアクティブにするトリガを作成するトリガが起動しますトリガのカスケードProblem:
トリガ(short form without ー) used inconsistently alongsideトリガーin the same file. User confirmedトリガーis the preferred term.Fix applied: All
トリガ→トリガー(in headings and prose, matched by particle: を/が/と/の/で)11. Broken Bold Markup
*/Develop-legacy/triggers.md(line 30, ×3 versions)Context:
Problem: Bold marker closes before the final ー, producing インスペクター instead of インスペクター.
Fix applied:
**インスペクタ**ー→**インスペクター**12. Grammar Error
*/Develop-legacy/triggers.md(line 247, ×3 versions)Context:
Problem:
使用してないでくださいis incorrect Japanese. The correct negative request form is使用しないでください.Fix applied:
使用してないでください→使用しないでください13. して下さい → してください
*/Develop-legacy/triggers.md(line 250, ×3 versions)Context:
Problem:
下さい(kanji) is inconsistent with the rest of the documentation which usesください(hiragana). Technical documentation style guides universally prefer hiragana for auxiliary verbs.Fix applied:
して下さい→してください14. Inconsistent Terminology: ユーザインターフェース
*/Develop-legacy/triggers.md(line 247, ×3 versions)Context:
Problem:
ユーザ(short form) used alongsideユーザー(long form) in the same file. User confirmedユーザーis preferred.Fix applied:
ユーザインターフェース→ユーザーインターフェース15. Stray Period
*/Develop-legacy/triggers.md(line 117, ×3 versions)Context:
Problem: Lone
.on its own line — likely an HTML export artifact.Fix applied: Removed the stray period line.
16. Empty 注: Markers
*/Develop-legacy/triggers.md(line 258, ×3 versions)*/language-legacy/Language/this.md(line 174, ×3 versions)Context:
Problem: Orphan
注:text appears before a proper:::noteadmonition. The注:is redundant (it was the HTML-era marker, now replaced by the:::notesyntax).Fix applied: Removed the empty
注:lines.17. Word-wrap Space Artifacts
*/Develop-legacy/triggers.md(line 256, ×3 versions)Context:
Problem: Spaces inserted mid-word from HTML line-break artifacts. Japanese text should not contain spaces within words.
Fix applied: Removed all mid-word spaces.
18. Broken Link: trucate-table
*/Develop-legacy/triggers.md(×3 versions)Context:
Problem: Missing 'n' in slug —
trucate-tableshould betruncate-table.Fix applied:
trucate-table→truncate-tableFinal Actionable Summary
✅ All issues have been fixed
All 28 findings across English and Japanese documentation have been addressed in PR #3 (branch:
miyako-docs-quality-audit).🔧 Global fixes applied
These corrections were applied via global search/replace across all version directories:
These files are managed by Crowdin for localization. If Crowdin overwrites changes on sync, the fixes may need to be applied to the Crowdin source strings instead. Coordinate with the Crowdin project admin to ensure persistence.