From fdf92bd553134c23f113fc6cebf8bf962a42c3d5 Mon Sep 17 00:00:00 2001 From: Doby2333 Date: Thu, 9 Apr 2026 11:19:46 -0700 Subject: [PATCH 1/3] docs: add Agent.md guide for AI doc contributions --- Agent.md | 117 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 Agent.md diff --git a/Agent.md b/Agent.md new file mode 100644 index 00000000..df0fe9fa --- /dev/null +++ b/Agent.md @@ -0,0 +1,117 @@ +# Agent.md + +Guidelines for AI assistants that create or update documentation in this repository. + +## Scope and Intent + +- Repository: `dynamsoft-docs/web-twain-docs` +- Product: Dynamic Web TWAIN documentation +- Primary goal: produce accurate, consistent Markdown docs that match existing repo conventions. +- Keep changes focused. Do not mix docs updates with local tooling/script changes unless explicitly requested. + +## Branching and PR Base + +- For normal docs work, branch from `preview` unless a different base is explicitly requested. +- Keep each PR focused on one topic (for example: one FAQ issue, one API clarification, one guide update). +- Avoid unrelated edits, formatting-only churn, and broad timestamp sweeps. + +## File Placement + +- FAQ pages live in `_articles/faq/`. +- General guides live in `_articles/general-usage/` or `_articles/extended-usage/`. +- API reference pages live in `_articles/info/api/`. +- When adding a new FAQ, also update `_articles/faq/index.md`. + +## Frontmatter Rules + +Use existing files in the same folder as the source of truth. + +### FAQ page template + +```yaml +--- +layout: default-layout +noTitleIndex: true +needAutoGenerateSidebar: true +title: +keywords: Dynamic Web TWAIN, +breadcrumbText: +description: +date: YYYY-MM-DD HH:mm:ss +0800 +last_modified: YYYY-MM-DD HH:mm:ss +0800 +--- +``` + +### Non-FAQ docs template (common) + +```yaml +--- +layout: default-layout +needAutoGenerateSidebar: true +title: +keywords: Dynamic Web TWAIN, +breadcrumbText: +description: +--- +``` + +Notes: +- `noTitleIndex` is common for FAQ and selected index-style pages; match nearby files. +- If updating an existing FAQ, update `last_modified` to current edit time and keep the existing date format. +- Keep timezone format consistent with the target file (many files use `+0800`; some newer files use `-08:00`). + +## FAQ Content Pattern + +For `_articles/faq/*.md`, match this structure: + +1. Category H1 (for example `# Addon`, `# Security`, `# Capture/Image Source`) +2. Question H2 (`## ...?`) +3. Direct answer first +4. Steps or code sample if applicable +5. Optional notes (`> [!NOTE]`) and related links + +Keep answers practical and implementation-oriented. + +## Writing Style + +- Be concise, technical, and specific. +- Prefer product terminology already used in repo: + - `DWTObject` + - `LoadImage()` / `LoadImageEx()` + - `SetReaderOptions()` + - `OnPostLoad` +- Do not introduce unsupported behavior claims. +- Do not mention internal tickets, private case history, or customer-identifying details in public docs. + +## Linking and API References + +- Use internal absolute doc links like: + - `/_articles/info/api/WebTwain_IO.md#loadimageex` +- Link API names to canonical API pages when mentioning methods/events. +- Prefer existing anchor patterns used in nearby docs. +- Keep external links to official pages only when necessary. + +## Code Snippet Rules + +- Use fenced code blocks with language tags (typically `javascript`, `html`, `bash`). +- Keep snippets minimal but runnable. +- Reuse existing coding style from surrounding docs: + - 4-space indentation in JS snippets is common. + - `DWTObject` naming is preferred in examples. + +## Safety and Accuracy Checks + +Before submitting changes: + +1. Verify every method/event name against `_articles/info/api/`. +2. Verify error code/value statements against docs or validated support guidance. +3. Ensure links resolve and anchors are valid. +4. Ensure new FAQ is added to `_articles/faq/index.md` in the correct section. +5. Ensure git diff includes only intended docs files. + +## Do Not Do + +- Do not edit local development scripts (`scripts/*.sh`, local-only files) for a docs-only task unless asked. +- Do not reformat large unrelated sections. +- Do not rename files casually; preserve existing URL paths. +- Do not add AI/meta commentary into user-facing docs. From a8d38756bc878ea102021e0158fb0e2984f02595 Mon Sep 17 00:00:00 2001 From: Doby2333 Date: Thu, 9 Apr 2026 11:22:42 -0700 Subject: [PATCH 2/3] docs(agent): clarify timezone uses committer local timezone --- Agent.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Agent.md b/Agent.md index df0fe9fa..8ac3b8fb 100644 --- a/Agent.md +++ b/Agent.md @@ -58,7 +58,7 @@ description: Notes: - `noTitleIndex` is common for FAQ and selected index-style pages; match nearby files. - If updating an existing FAQ, update `last_modified` to current edit time and keep the existing date format. -- Keep timezone format consistent with the target file (many files use `+0800`; some newer files use `-08:00`). +- Use the committer's local timezone for `date` / `last_modified` (for example, `+0800` for UTC+8 users). ## FAQ Content Pattern From b4aaa12d888b93f5e3c368a18883557992d486a6 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 21 Apr 2026 23:10:37 +0000 Subject: [PATCH 3/3] docs(agent): generalize FAQ timezone/offset template guidance Agent-Logs-Url: https://github.com/dynamsoft-docs/web-twain-docs/sessions/d9dd3db5-7aa6-4981-bb4f-b1c2182b8258 Co-authored-by: lyzhang0113 <35015690+lyzhang0113@users.noreply.github.com> --- Agent.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/Agent.md b/Agent.md index 8ac3b8fb..690f8ae5 100644 --- a/Agent.md +++ b/Agent.md @@ -37,8 +37,8 @@ title: keywords: Dynamic Web TWAIN, breadcrumbText: description: -date: YYYY-MM-DD HH:mm:ss +0800 -last_modified: YYYY-MM-DD HH:mm:ss +0800 +date: YYYY-MM-DD HH:mm:ss ±HHMM (or ±HH:MM) +last_modified: YYYY-MM-DD HH:mm:ss ±HHMM (or ±HH:MM) --- ``` @@ -57,8 +57,7 @@ description: Notes: - `noTitleIndex` is common for FAQ and selected index-style pages; match nearby files. -- If updating an existing FAQ, update `last_modified` to current edit time and keep the existing date format. -- Use the committer's local timezone for `date` / `last_modified` (for example, `+0800` for UTC+8 users). +- If updating an existing FAQ, update `last_modified` to current edit time and match the exact datetime/offset format used by nearby files in the same folder. ## FAQ Content Pattern