Skip to content

docs: README repeats its intro, leads with managed install, and lists limitations that may be stale #69

Closed

Description

@iguangfei

Observation on main faf1d88 (1.9.8)

  1. Duplicated intro. README.md:15 and README.md:18 are two versions of the same opening paragraph ("Deckuse is a local-first, schema-driven Office document automation engine for coding agents…").
  2. First screen is installation plumbing. The sections above the fold are "Agent quick start", "Install in a managed agent job" and "Create an editable PPTX from the installed example". "Why Deckuse" starts at line 85 and "Where it creates value" at line 99. The README contains no screenshot, GIF or video.
  3. Limitations and capability bullets may lag the code. These lines should be re-checked against current behavior and the pending changesets (.changeset/native-office-review.md, .changeset/safe-office-data-and-review.md):
    • README.md:440 "Chart creation and edits update OOXML chart caches only; embedded Excel workbooks are not rewritten." — src/pptx/chart-workbook.ts exists and the changeset mentions bounded embedded workbook synchronization.
    • README.md:443 "setText and replaceText collapse multi-run text…" — the changeset says DOCX replacement formatting is now preserved.
    • README.md:411 "Tracked changes… are preserved. A command that would have to rewrite them fails" — src/docx/revisions.ts and docs/review.md describe tracked-change proposals with atomic accept/reject, and native comment threads. None of this appears in the README capability lists.
    • README.md:95 "Semantic diff / branch remain deferred past Phase 1a."
  4. Scattered version references. README.md:44 pins the bootstrap example to 1.9.3; README.md:401 says "Requires CLI >= 1.2.0"; the format badge at the top lists PPTX only although DOCX is implemented.
  5. Translations have drifted. README.md is 474 lines, README.zh-CN.md is 392, and the other six are 342 each.

I have not run each limitation end to end; item 3 is a list of lines to verify, not a claim that all of them are wrong.

Suggested direction

  • Open with one paragraph on what Deckuse does, one visual, and the four "Where it creates value" bullets; move managed-job installation below.
  • Add the review capabilities (comments, tracked-change proposals) to the capability lists once verified.
  • Replace hard-coded versions with a single "current version" reference, or state the minimum once.
  • Decide which translations are maintained; remove or mark the rest as community-maintained.

Acceptance

  • One intro paragraph.
  • What/why and a visual appear before installation details.
  • Every Limitations bullet is verified against 1.9.x behavior.
  • Version references are consistent.
  • Each remaining translation matches the English structure or is clearly marked as partial.

Activity

  1. zhaoxiongfei commented on Nov 13, 2026

    @zhaoxiongfei
    Member

    README 将用途、操作流程和原生 PowerPoint 示例移至安装之前,更新工作簿同步、Word 评论和修订、文本格式及预览限制。七份翻译标记为部分翻译。打包 README 回归和完整测试通过。

    已随 PR #74 合并到 main(46ff80d)。GitHub 两组 CI、本地 470 项测试和 npm 安装包检查通过。
    #74

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions