SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsexternal-mindstudio-document-ux-review

external-mindstudio-document-ux-review

Writing & research

View repository

Updated 10-15 17:19

About this skill

Document UX Review

The goal of this skill is not to "read the README once and offer a few comments," but to treat yourself as a user encountering the project for the first time, operate step by step according to the documentation in as realistic an environment as possible, cover every stage in the documentation as much as possible, find the problems that will actually block onboarding, and provide actionable improvement suggestions.

Scope of application

  • The input is usually a Git repository link, but it can also be a local repository path.
  • The default review scope is:README + README The installation, quick start, and run-related documentation directly pointed to.
  • If the README jumps key steps to docs/, scripts, example directories, or other Markdown files, continue to follow up on these directly dependent documents.
  • Do not read all documentation without boundaries; maintain a sense of scope of "read whatever must be read in order to complete the process guided by the README."

Confirm execution boundaries before starting

Before actually executing, first confirm the following information as much as possible, to avoid misjudging environment problems as documentation problems, and to avoid repeatedly installing basic components the user already has:

  • Operating system, Shell, CPU architecture.
  • Whether there is an acceleration environment such as GPU / NPU, and which basic environments are already installed, for example CUDA, CANN, compilers, Docker.
  • Whether the user wants to skip installation of basic components they already have and only experience the remaining documentation process.
  • Whether Docker,uv、Python venv、conda, local Node version management, and other isolation methods are allowed.
  • Whether there are restrictions such as network, permissions, proxy, corporate intranet, disk space, port occupancy, etc.
  • Whether logging in to external services, filling in keys, and accessing cloud resources are allowed.

If the user has not provided enough information:

  • Clearly write out your environment assumptions and continue.
  • Record "risks caused by missing environment information" separately in the report.

If the user explicitly says that certain basic environments are already OK:

  • Do not reinstall them.
  • First verify whether these environments are truly usable, then start experiencing from the next step in the documentation.
  • State in the report "which steps were skipped based on the user's declaration."
  • If the current host environment clearly does not match the documentation's target environment, and the user allows Docker or another isolation solution, preferentially switch to a platform closer to the documentation's target and continue experiencing, and record this as an "execution deviation." For example: the host machine is macOS, but the documentation is clearly oriented to a Linux installation environment; in this case, preferentially consider a Docker Linux container rather than forcing guesses and patches on the host machine.

Environment safety principles

Try not to pollute the host environment, and do not affect other users:

  • Preferentially use isolation solutions, such as Docker,uv、Python venv、conda, local project dependencies, and temporary directories.
  • Unless the documentation explicitly requires it and the user accepts it, do not modify global configuration, system-level packages, shared directories, or the user's existing environment.
  • If the documentation can only be completed through global installation or high-risk steps, record this first; if necessary, pause and explain the risks to the user.
  • Do not silently fix the document for the user. Any deviation made for safety, isolation, or compatibility must be explicitly recorded in the report as an "execution deviation."
  • When there are multiple isolation options, prioritize the option that is both close to the document's target environment and has the fewest side effects; do not casually switch to a different execution path just because you are familiar with a certain tool.

Execution Principles

1. Follow the document strictly

  • Execute in the order of the README, then continue by following the key documents directly referenced by the README.
  • Execute the commands, paths, environment variables, and step order in the document as literally as possible.
  • Do not automatically fill in missing steps in your head and then pretend it "can run through." If you need to infer, search for additional information, or correct commands, it means the document itself already has problems.
  • Each step must record the "document basis," including at least one of the following: document path, chapter title or section name, original command or key excerpt from the source text. Do not write vague statements like "according to the README."

2. Review from a beginner's perspective

Treat yourself as someone encountering the project for the first time, and focus on:

  • Whether the prerequisites are clearly stated.
  • Whether the commands can be directly copied and executed.
  • Whether variable names, path names, placeholders, branch names, and image names are clearly explained.
  • Whether the expected output after successful execution is clearly written.
  • Whether troubleshooting directions are given upon failure.
  • Whether the document assumes readers know certain context, but the document does not explicitly state it.

3. Actually verify until "it can start" or "it is blocked by the document"

  • If the document requires installing dependencies, generating configuration, starting services, or running a demo, try to actually complete these steps as much as possible.
  • If the project can start successfully, record evidence of "running through according to the document," such as startup logs, access results, or test command output.
  • If blocked, do not force your way around it and make the result look "completed"; accurately record the blocking point, the missing prerequisites, and possible documentation defects.

4. Situations where stopping is allowed

In the following situations, you may stop continuing that branch and record it as a blocking item in the report:

  • Requires real accounts, keys, verification codes, paid resources, or the company's internal network.
  • Requires high-risk system changes, root privileges, or destructive commands.
  • Requires special hardware or external dependencies that are not declared in the document but are actually necessary.
  • The execution cost is too high, clearly beyond the scope of "document onboarding verification," such as long training tasks.

When stopping, write clearly:

  • At which step it stopped.
  • What the document said at that time.
  • What the actual blocker is.
  • Whether this is an environment limitation, or whether the document failed to explain it in advance.

Review Checklist

Check at least from the following dimensions:

Usability

  • Whether newcomers know where to start.
  • Whether the step order is natural and can be followed unambiguously.
  • Whether commands can be directly copied, and whether users need to guess paths, versions, or variable values.
  • Whether there are branch instructions suitable for different environments, such as macOS / Linux / Windows, CPU / GPU, Docker / non-Docker.

Correctness

  • Whether commands, package names, paths, file names, and environment variable names are correct.
  • Whether the installation and running steps are complete, whether there are missing steps, incorrect order, or omitted dependencies.
  • Whether the results promised by the documentation can actually occur.
  • Whether the version requirements are consistent with the project's current state.

Readability

  • Whether the terminology is explained clearly.
  • Whether paragraphs, headings, and code blocks are organized reasonably.
  • Whether placeholders are clear, for example <your-path>、<model-name> where values of this kind come from.
  • Whether success results, failure results, and notes are easy to scan.
  • Whether novice users can easily understand "which step has currently been reached, why it succeeded/failed, and what to do next".

Completeness

  • Whether the prerequisite environment, dependency versions, system requirements, permission requirements, and network requirements are explained.
  • Whether initialization data, configuration files, sample input, and sample output are provided.
  • Whether verification steps are included, rather than only installation commands.
  • Whether common errors and troubleshooting methods are explained.

Environment friendliness and best practices

  • Whether the use of isolated environments is encouraged, to avoid polluting the system.
  • Whether it avoids requiring global installation, global PATH changes, or modification of shared configurations by default.
  • Whether a minimal viable verification path is provided, rather than making users first perform a large amount of irreversible configuration.
  • Whether it explains "why this should be done" where necessary, to help beginners build a mental model.

Key sections and industry practices of open source projects

In addition to checking whether it "can run successfully", also examine whether this documentation has the key content commonly found in mature open source projects. At least check whether the following items are clear, missing, or only partially present:

  • Supported platforms / compatibility matrix.
  • Prerequisite environment requirements and version requirements.
  • Installation guide.
  • Quick start / minimal runnable verification path.
  • Configuration instructions and placeholder explanations.
  • Troubleshooting / FAQ.
  • Getting-started guidance for novice users, such as success indicators and next steps after failure.
  • Recommendations for security, isolated environments, or use in shared environments.
  • If the installation, startup, verification, or configuration methods can only be inferred by reading source code, scripts, CI configuration, Dockerfile, Makefile, or test cases, this must be explicitly recorded as a "documentation completeness" issue; do not count it as documentation usability just because you ultimately got it running by reading the code.

If these sections do not exist strictly as separate headings, judge from the content level whether they are covered, rather than only looking at directory names.

Evidence recording requirements

For each problem found, provide precise evidence as much as possible:

  • Documentation location: for example README.md:42、docs/install.md:18; if an exact line number cannot be obtained, at least write the section title.
  • Original basis: as much as possible, add a short excerpt of the original command, placeholder, or key original text, to help readers quickly compare.
  • The commands actually executed.
  • The actual output or error summary.
  • Whether this is a failure when executed exactly as written, or a deviation made for safety / compatibility.
  • Whether source code, scripts, configuration, or CI files were additionally read in order to continue execution; if they were read, which documentation should have provided this information.
  • What impact this will have on beginners.

Do not write only vague judgments, such as "the documentation is unclear" or "the command seems problematic." Try to compress the problem into reproducible, modifiable, and verifiable items.

Severity definitions

  • 阻塞: A newcomer cannot continue following the documentation, or the core process cannot be run through at all.
  • 高: Obvious additional knowledge, trial and error, or manual correction is required to continue, severely affecting onboarding efficiency.
  • 中: It does not immediately block progress, but it easily misleads, wastes time, or causes misunderstandings.
  • 低: Optimization items such as wording, formatting, and example quality that do not affect completion of the main process.

Workflow

1. Prepare the workspace

  • Prefer to operate in a temporary directory; do not pollute the user's existing repository.
  • After cloning or entering the target repository, first locate the default branch and the current README.
  • Create a brief execution plan: which documents you plan to follow, what isolation method you plan to use, and which steps may be limited by the environment.

2. Sort out the documentation execution path

  • First read README。
  • Identify the prerequisites, installation steps, configuration steps, startup steps, and verification steps in it.
  • Trace the key documents directly referenced by the README, and organize them into an execution order.
  • If you must read source code, scripts, Makefile, CI, or Dockerfile to know how to proceed to the next step, you may read them to help locate the problem, but you must record this kind of "completion outside the documentation" separately as a completeness defect, rather than treating it as already covered by the documentation.

3. Execute step by step and record

  • For each step, record what the documentation said, what you actually did, and what the result was.
  • For situations such as "the command is incomplete," "the documentation assumes a component is already installed," or "the success criteria are not written," record the problem immediately; do not wait until the end to recall it.
  • If a step succeeds, also state the basis for success, so readers can understand which nodes in the entire process are OK, rather than only seeing the failure items.

4. Make a best-practices comparison

  • After completing the experience or being blocked, go back and add another round of review from the perspective of best practices.
  • Pay special attention to: environment isolation, transparency of prerequisites, clarity of platform branches, success verification paths, and troubleshooting instructions.

5. Output a standardized report and render HTML

The final report uses Chinese by default, and retains the original commands and English error messages when necessary. Unless the user requests otherwise, first organize it into the standardized report structure below, then render it into the final HTML report for delivery to the user. This Markdown structure is the intermediate standard form; the final deliverable should be HTML, not merely Markdown text. If the final report will produce multiple HTML pages, they must be delivered in the same separate folder; do not throw scattered HTML files directly into the workspace root directory.

Report format

Organize strictly according to this structure; a small number of subitems may be added or removed within each section, but do not omit core information:

# 文档体验审查报告

## 1. 审查对象
- 仓库：
- 审查范围：README + 直接关联文档
- 审查时间：
- 评审分支：
- 评审提交：
- 体验环境：
- 用户声明的已具备环境：
- 采用的隔离策略：

## 2. 总体评分与结论
- 总体评分：`XX/100`
- 评分拆解：正确性 / 易用性 / 可读性 / 完整性 / 环境友好性
- 是否按文档走通：完全走通 / 部分走通 / 未走通
- 结论基线：`<评审分支> @ <评审提交>`
- 总体评价：
- 主要风险：

## 3. 体验流程图
| 步骤 | 文档依据 | 预期动作 | 状态 | 现象 / 结果 | 阻塞原因或成功依据 | 严重程度 |
| --- | --- | --- | --- | --- | --- | --- |

状态建议使用：`OK` / `偏差继续` / `阻塞` / `未执行`

## 4. 执行过程摘要
| 阶段 | 文档依据 | 实际执行 | 结果 | 备注 |
| --- | --- | --- | --- | --- |

## 5. 关键问题概览
| ID | 严重程度 | 分类 | 文档位置 | 问题简述 |
| --- | --- | --- | --- | --- |

## 6. 详细问题

### ISSUE-01 标题
- 严重程度：
- 分类：易用性 / 正确性 / 可读性 / 完整性 / 最佳实践
- 文档位置：
- 文档原文 / 摘录：尽量贴出短摘录、命令片段或占位符原文，帮助读者快速对应原始文档
- 复现上下文：
- 实际现象：
- 影响分析：说明为什么这会让新手卡住、误解或高成本试错
- 修改建议：给出可直接落地的写法、补充步骤或结构调整建议

## 7. 新手友好度观察
- 从小白视角总结：这份文档哪些地方容易迷路、需要猜测、缺少成功/失败判定，哪些地方做得相对友好。
- 文档是否齐全，是否有明显的漏步骤、错步骤，是否有不合理的前置条件假设。
- 如果要靠阅读源码、脚本、CI、Dockerfile、Makefile 或 issue 才能理解如何继续，这本身就是文档完整性问题，要明确写出缺失的文档信息，而不是把“靠自己读代码补齐”视为走通。

## 8. 正向观察
- 写出文档做得好的地方，帮助用户区分“保留什么”和“该改什么”。

## 9. 优先修复建议
1. 先修复阻塞主流程的问题。
2. 再补齐前置条件和验证步骤。
3. 最后优化可读性和最佳实践提示。

## 10. 附录
- 执行中使用的关键命令：
- 关键报错摘要：
- 执行偏差说明：
- 因环境限制未继续的步骤：

Scoring explanation

  • 90-100: Beginners can basically follow the documentation directly, with only minor optimization items.
  • 75-89: The main process is generally usable, but there are obvious shortcomings in readability, environment description, or troubleshooting.
  • 60-74: More manual judgment or additional knowledge is required to get through, and the experience is average.
  • 40-59: The documentation has obvious blockers, missing steps, or unclear platform/dependency information, making it difficult for ordinary users to complete smoothly.
  • 0-39: The main process cannot be executed according to the documentation, and the critical path is severely distorted or missing.

Output requirements

  • The final deliverable should be an HTML report, placed in a separate folder. A single scenario can have just 1 HTML, or it can be an overview HTML + detail HTML; multiple scenarios should output one overview HTML plus scenario detail HTML. In either case, all HTML files should be located in the same report directory.
  • If you generated report files in the local workspace, you should also state the file paths in your reply.
  • Conclusions must be based on real execution evidence or explicitly stated assumptions; do not present guesses as facts.
  • If no obvious problems are found, you should still explain which steps, which documents, and which run results you actually checked.
  • The beginning of the report must give an overall score on a 100-point scale and explain the basis for the score.
  • The overall conclusion must clearly state the review branch and commit id corresponding to this conclusion; do not bury this information only in an appendix, file name, or execution log.
  • The report must provide a complete experience flow diagram or flow table, clearly indicating which step is OK, which step is blocked, what the blocking phenomenon is, what the cause is, and what the severity is.
  • For each key step and issue, prioritize giving a combination of "documentation basis + original text excerpt + actual phenomenon," rather than only giving line number ranges.
  • The UI style, color scheme, information hierarchy, and card / tag / timeline / table styles of the final HTML report should be consistent with those defined by scripts/render_report_html.py ; do not switch to another visual language on your own.
  • The final HTML should be the report itself, not a review interface with page turning, feedback buttons, or a benchmark.
  • If a standardized Markdown report needs to be converted into the final HTML, the bundled script should be used first:scripts/render_report_html.py, and the style and structure generated by that script should prevail.

Prohibitions

  • Do not disguise problems you privately fixed as "the documentation was already usable."
  • Do not secretly skip key steps just to get it running, yet write in the conclusion that it "can be used normally."
  • Do not assume by default that the user is willing to accept global installation, root privileges, system pollution, or shared environment modifications.
  • Do not give only abstract suggestions; you must give specific locations and executable fixes.