Documentation proposal: non-firmware component docs and dual-track cookbooks

[JusterZhu]

Background

We need to update the online documentation in GeneralLibrary/GeneralUpdate-Samples based on the current components in GeneralLibrary/GeneralUpdate. The firmware update component is explicitly out of scope. In addition, the documentation should include two cookbook tracks: one for first-time users and one for experienced developers. The cookbook content should be written together with the workflow provided by GeneralLibrary/GeneralUpdate.Tools.

I have reviewed the key structure across the three repositories:

• GeneralUpdate currently contains GeneralUpdate.Core, GeneralUpdate.Bowl, GeneralUpdate.Differential, GeneralUpdate.Drivelution, GeneralUpdate.Extension, and GeneralUpdate.Firmware. This proposal excludes GeneralUpdate.Firmware.
• GeneralUpdate-Samples already hosts a Docusaurus documentation site under website/docs, with localized copies under website/i18n/en/... and website/i18n/zh-Hans/.... Existing component pages cover some topics, but they do not yet provide a complete path from component purpose, to usage, to runnable samples, to tool-generated artifacts, to troubleshooting.
• GeneralUpdate.Tools is an Avalonia 12 + Semi Theme desktop tool for patch packages, extension packages, OSS configuration, simulation, reports, and hashes. It should be integrated into the cookbook as the practical packaging and verification workflow.

Proposed documentation scope

The online documentation should cover the following non-firmware components:

Component	Documentation focus
GeneralUpdate.Core	Upgrade helper responsibilities, bootstrap flow, download and replacement process, events, exceptions, OSS mode, normal server mode, and relation to Client/Upgrade/Samples.
GeneralUpdate.Bowl	Post-upgrade startup monitoring, crash detection, backup restoration, dump/trace output, and where it fits in the upgrade lifecycle.
GeneralUpdate.Differential	Old/new directory comparison, incremental patch generation, patch application, deleted file manifest, and its relation to Tools Patch Package output.
GeneralUpdate.Drivelution	Cross-platform driver update management, validation, backup, rollback, permissions, platform differences, and enterprise/device scenarios.
GeneralUpdate.Extension	VS Code-like extension system, extension metadata, download/install/update/rollback, dependency and compatibility checks, and relation to Tools Extension Package output.

GeneralUpdate.Firmware should remain out of scope for this work to avoid mixing firmware OTA concepts with application update documentation.

Proposed documentation structure

Keep the existing Docusaurus site and organize new or updated pages under website/docs:

• doc/components/overview.md: component overview, selection guide, and architecture diagram.
• doc/components/core.md
• doc/components/bowl.md
• doc/components/differential.md
• doc/components/drivelution.md
• doc/components/extension.md
• cookbook/beginner/: beginner cookbook.
• cookbook/advanced/: advanced cookbook.
• tools/: GeneralUpdate.Tools installation, execution, artifact descriptions, field reference, and troubleshooting.

The same structure should be kept in sync for:

• website/docs/...
• website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/...
• website/i18n/en/docusaurus-plugin-content-docs/current/...

This keeps the Chinese and English documentation aligned.

Component page template

Each component page should follow the same template:

1. What problem this component solves.
2. When to use it and when not to use it.
3. Package name and target framework.
4. Core objects and APIs.
5. Minimal runnable example.
6. Related sample project in GeneralUpdate-Samples.
7. How it consumes or produces artifacts from GeneralUpdate.Tools.
8. Common errors and troubleshooting checklist.
9. Advanced configuration and production notes.

Beginner cookbook

Goal: help first-time users run through a complete update flow quickly without needing to understand every internal detail first.

Suggested chapters:

1. Understand the five roles: Client, Upgrade, Packet, Server, and Tools.
2. Run the smallest working sample from GeneralUpdate-Samples/src.
3. Use GeneralUpdate.Tools to generate the first Patch Package.
4. Publish the package to local storage, OSS, or the sample server.
5. Start the Client, trigger an update, and observe the Upgrade process.
6. Add Bowl monitoring and verify recovery when the upgraded application fails to start.
7. Use Differential to understand why incremental packages are smaller.
8. Troubleshooting: paths, version numbers, file locks, permissions, antivirus software, and Linux execute permissions.

The beginner cookbook should use concrete commands, screenshots or tables, and clear success criteria instead of starting with a large API reference.

Advanced cookbook

Goal: help experienced developers integrate GeneralUpdate into real products, CI/CD pipelines, and enterprise release workflows.

Suggested chapters:

1. Design a production update architecture: Client, Upgrade, Server, OSS, Tools, and CI.
2. Standardize release artifacts with GeneralUpdate.Tools: application package, patch package, extension package, and OSS configuration.
3. Integrate Patch Package generation into GitHub Actions or an internal CI pipeline.
4. Version strategy: SemVer, branch releases, staged rollout, forced updates, and multi-version sequential upgrades.
5. Differential strategy: when to use it, how to handle deleted files, blacklists, and large files.
6. Reliability strategy: Bowl monitoring, backup, rollback, startup validation, and log collection.
7. Extension system: extension manifest, extension package publishing, compatibility, and dependency management.
8. Driver updates: Drivelution permissions, signatures, platform differences, rollback, and restart strategy.
9. Security and compliance: hash validation, authenticated downloads, OSS permissions, and release audit.
10. Failure drills: simulate download failure, file lock, startup crash, corrupted patch, and insufficient permissions.

How GeneralUpdate.Tools should be integrated

The cookbook should not treat Tools as a separate unrelated project. It should be embedded into real workflows:

• Patch Package: used in Differential and standard application update chapters.
• Extension Package: used in Extension publishing chapters.
• OSS Config: used in OSS update mode and static file hosting chapters.
• Simulation: used in pre-release validation chapters.
• Report and Hash: used in production release checklists.

The documentation should clearly describe the inputs, outputs, and where those outputs are consumed by GeneralUpdate, including old version directory, new version directory, output patch zip, delete_files.json, manifest files, OSS version JSON, and hashes.

Open questions

• Should the implementation write Chinese first and then synchronize English, or complete both languages in one pass?
• Should existing pages such as GeneralUpdate.ClientCore.md and GeneralClient.OSS.md remain as compatibility pages, or should they be merged into the new component structure?
• Should the Tools documentation include screenshots? If yes, the implementation can reserve screenshot locations and add images based on the current UI.

Expected deliverables

After implementation, the Samples repository should contain:

• Complete online documentation for all non-firmware GeneralUpdate components.
• Beginner cookbook: first complete update flow from zero.
• Advanced cookbook: production, automation, and extension-oriented integration guide.
• GeneralUpdate.Tools usage guide and artifact reference.
• Consistent Chinese and English documentation structure.

[JusterZhu]

Sub-issue tracking

Created the following implementation subtasks for #45:

• Docs subtask: define Docusaurus information architecture and i18n layout #46 - Docs subtask: define Docusaurus information architecture and i18n layout
• Docs subtask: update GeneralUpdate.Core component documentation #47 - Docs subtask: update GeneralUpdate.Core component documentation
• Docs subtask: update GeneralUpdate.Bowl component documentation #48 - Docs subtask: update GeneralUpdate.Bowl component documentation
• Docs subtask: update GeneralUpdate.Differential component documentation #49 - Docs subtask: update GeneralUpdate.Differential component documentation
• Docs subtask: update GeneralUpdate.Drivelution component documentation #50 - Docs subtask: update GeneralUpdate.Drivelution component documentation
• Docs subtask: update GeneralUpdate.Extension component documentation #51 - Docs subtask: update GeneralUpdate.Extension component documentation
• Docs subtask: document GeneralUpdate.Tools workflows and artifacts #52 - Docs subtask: document GeneralUpdate.Tools workflows and artifacts
• Docs subtask: write beginner cookbook for first-time GeneralUpdate users #53 - Docs subtask: write beginner cookbook for first-time GeneralUpdate users
• Docs subtask: write advanced cookbook for production and automation workflows #54 - Docs subtask: write advanced cookbook for production and automation workflows
• Docs subtask: final consistency review and documentation validation #55 - Docs subtask: final consistency review and documentation validation

These issues are intentionally written in English and grouped by component, cookbook track, tooling, and final validation.