5.1 KiB
5.1 KiB
README And Beginner Guide Requirements
Goal
为当前抖音视频爬取项目补齐两层面向用户的文档，使一个不懂代码的 Mac 用户也能按照步骤执行，并最终成功下载出抖音视频。
本次文档需求包含两部分：
- 仓库根目录的
README.md externaldocs/下的详细图文操作手册
本需求文档只定义文档目标、范围、结构、截图策略和约束，不直接修改实现代码。
Target Audience
目标读者是：
- 使用 macOS 的用户
- 不懂代码
- 不熟悉 Python
- 不熟悉虚拟环境
- 但已经把项目放到了本地机器上
本次文档不负责指导用户如何 git clone 或下载项目源码到本地。
Documentation Strategy
采用双层文档结构：
1. Root README.md
README.md 作为导航版首页，职责是：
- 简要说明项目是什么
- 说明项目能做什么
- 说明项目不能做什么
- 告诉用户从哪里开始
- 引导用户查看详细图文手册
README.md 不承担完整教学职责，不写成超长操作文档。
2. Detailed Guide In externaldocs/
详细图文手册作为主操作文档，职责是：
- 面向完全不会代码的用户
- 从环境准备开始写
- 一步一步带到成功下载出视频
- 给出执行命令、预期结果和失败时的处理方式
Scope
Included
详细图文手册必须覆盖以下内容：
- 项目简介
- 使用前准备
- 如何确认本机已安装 Python
- 如何打开终端
- 如何进入项目目录
- 如何创建或使用虚拟环境
- 如何安装依赖
- 如何启动登录浏览器
- 如何在浏览器中完成抖音登录和验证码
- 如何运行抓取命令
- 如何确认抓取成功
- 下载结果保存在哪里
- 常见错误及处理办法
Excluded
本次文档明确不包含以下内容：
- 如何从远端拉取项目代码到本地
- Git 基础教学
- 任意网页抓取教学
- 非 Mac 平台的安装说明
- 抖音接口原理深度分析
README Requirements
README.md 必须满足以下要求：
- 用非技术语言介绍项目用途
- 明确说明这是一个“登录浏览器后附着抓取”的工具
- 简短说明当前项目的主要能力
- 简短说明当前项目的限制
- 提供“最快开始”入口
- 链接到
externaldocs/下的详细图文手册
Recommended README Sections
- 项目简介
- 适用人群
- 当前支持的能力
- 快速开始
- 详细使用说明
- 常见注意事项
Detailed Guide Requirements
详细图文手册必须写成严格的步骤式说明，适合完全不会代码的读者照做。
Writing Style
- 不使用不必要术语
- 每一步只做一件事
- 每一步都给出要执行的命令
- 每一步都给出“执行后应该看到什么”
- 若这一步常见失败，则紧跟“如果失败怎么办”
Required Workflow Coverage
详细手册必须按以下顺序组织主流程：
- 确认 Python 是否已安装
- 打开终端
- 进入项目目录
- 创建或启用虚拟环境
- 安装依赖
- 启动登录浏览器
- 在浏览器中完成抖音登录
- 运行抓取命令
- 查看终端成功提示
- 在本地查看下载出来的 mp4 文件
Screenshot Strategy
本次截图必须重新拍摄，不直接复用旧图。
Principles
- 只截关键步骤
- 每张图只服务一个步骤
- 截图内容要与最终文档步骤严格一致
- 优先保证“能照着做”，而不是“图多”
Required Screenshot Topics
至少应考虑覆盖以下截图：
- 项目目录结构
- 打开终端并进入项目目录
- 安装依赖命令
- 运行
login_douyin.py - 浏览器登录后的状态
- 运行抓取命令
- 成功下载后的
video/目录
Screenshot Placement
README.md只放少量必要截图或不放截图- 主要截图集中放在详细图文手册中
Success Signals In The Guide
文档里必须明确告诉用户如何判断是否成功，至少包括：
- 终端中会出现哪些关键信息
- 抓取完成后会看到哪些成功提示
- 本地哪个目录里能看到下载结果
- 下载出的文件是什么格式
Common Error Handling
详细图文手册必须包含至少以下常见错误的处理建议：
- 系统找不到
python或.venv - 依赖安装失败
- Chrome 调试端口未就绪
- 抖音登录未完成或验证码未通过
- 运行抓取后没有下载出视频
- 看不到
video/目录或目录为空
TDD Constraint
本次文档需求本身不要求用 TDD 编写文档。
但如果为了让文档步骤成立而需要修改代码，则后续代码改动必须遵循 TDD：
- 先写失败测试
- 确认测试因功能未实现而失败
- 再写最小实现让测试通过
- 最后再重构
Acceptance Criteria
该需求完成后，应满足以下标准：
- 仓库首页有清晰的
README.md README.md能让用户快速理解项目并找到详细手册externaldocs/下存在一份完整的面向小白的图文操作手册- 一个不会代码的 Mac 用户可以按手册独立完成操作
- 手册能从环境准备一路带到视频下载成功
- 手册包含关键截图、预期结果和常见错误处理