Documentation Maintenance Conventions

Documentation Maintenance Conventions

中文

General principles

• The GitHub Wiki is the primary documentation entry point.
• Whenever an English topic page is maintained, maintain its complete Chinese counterpart in the same change. Each language uses a readable filename in that language.
• Chinese and English pages link to each other near the top and describe the same current facts; the English page is not an abbreviated summary.
• Documentation follows the actual current code.
• Remove clearly obsolete information from primary navigation.
• Do not maintain parallel technical Markdown sets in both the wiki and docs; consolidate maintained technical material in the wiki.
• Prefer root-level GitHub Wiki page names rather than subdirectory links.
• The wiki repository is always the outer project root's external/wiki/ directory. Do not create wiki documentation in the Screen-Remote/ app subrepository.

File and title naming

• The home page is Home.md.
• The sidebar is _Sidebar.md.
• Primary English entries are User-Documentation.md and Developer-Documentation.md; the Chinese entries are 用户使用文档.md and 开发文档.md.
• Child pages use readable filenames in their own language.
• For example, use Architecture.md and 开发文档-架构.md for one bilingual topic.
• The technical documentation index is Technical-Documentation-Index.md.
• Use readable level-one titles without repeating the document-group prefix.
• Keep established technical spellings such as ADB, dadb, and scrcpy 4.1.
• In the sidebar, use grouped headings and page links rather than plain list items for group names.

User documentation

• Explain how to use the product.
• Avoid unnecessary implementation detail.
• Exclude one-off debugging narratives.
• Focus on entry points, limitations, and precautions.

Developer documentation

• Describe the current structure, flows, and important implementation behavior.
• Map statements to real repository paths.
• Prefer conclusions over long code excerpts.
• Wiki pages provide navigation and retain technical details that remain useful.

Bilingual synchronization acceptance

• Every Chinese and English page must exist as a one-to-one pair, and language links near the top must navigate in both directions.
• Both languages retain the same section structure and knowledge coverage. Tables, formulas, configuration values, code paths, behavioral constraints, and regression checks must not be missing from either language.
• When correcting an obsolete conclusion, use current code and tests as the source of truth, then search all wiki Markdown for equivalent stale wording so other pages do not continue spreading the old fact.
• Before delivery, validate local link targets, Markdown diffs, and section correspondence for every new or changed page. The existence of an English file alone does not prove content consistency.

When to update

Synchronize the Chinese and English wiki pages when:

• session parameters materially change;
• ADB behavior changes;
• scrcpy-server is upgraded;
• management capabilities are added or removed; or
• an existing documented conclusion becomes false.

README conventions

• Root README.md and README_CN.md are limited to the project introduction, interface previews, and direct GitHub Wiki navigation; they do not carry detailed technical or user documentation.
• The outer-root docs/ directory contains media assets only, such as screenshots. Do not create or maintain Markdown there; project, contribution, release, user, developer, and protocol documentation all belong in the wiki.
• The wiki contains a complete technical index so maintained knowledge is discoverable.

Deduplication

• Keep one canonical detail page for each topic.
• Entry pages provide navigation and reading paths without duplicating technical explanations.
• When a short summary and a longer technical page cover the same topic, merge unique conclusions into the canonical page, delete the duplicate, and repair links.
• During the initialization audit, place every old page in Wiki Initialization and Update Checklist and decide whether to keep, merge, split, archive, or delete it.
• Only retained Chinese pages require English counterparts. Do not create English shells for pages that will be merged or deleted.

Recently consolidated topics

• scrcpy 4.1 upgrade and protocol adaptation
• dadb Android mDNS discovery
• IPv6 sessions and endpoint handling
• stable Surface behavior in fullscreen mode
• process-page scope and performance expectations
• codec-filter completion
• wiki sidebar grouping, overview indexes, and naming rules
• migration of historical docs technical Markdown into the wiki