Back to Details

documentation-tools

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Tools

文档工具

Static Site Generators

静态网站生成器

Docusaurus

Docusaurus

  • Framework: React-based static site generator
  • Features: Versioned docs, blog, i18n support, search
  • Deployment: Easy deployment to GitHub Pages, Netlify, Vercel
  • Plugins: Extensible plugin ecosystem
  • Theme: Customizable themes and components
  • Use Cases: Open source projects, product documentation
  • 框架：基于React的静态网站生成器
  • 特性：版本化文档、博客、多语言支持、搜索功能
  • 部署：可轻松部署至GitHub Pages、Netlify、Vercel
  • 插件：可扩展的插件生态系统
  • 主题：可自定义的主题与组件
  • 适用场景：开源项目、产品文档

MkDocs

MkDocs

  • Framework: Python-based static site generator
  • Features: Simple configuration, fast builds, theme support
  • Deployment: Static HTML output, deploy anywhere
  • Plugins: Rich plugin ecosystem for extensions
  • Theme: Material theme, ReadTheDocs theme, custom themes
  • Use Cases: Python projects, technical documentation
  • 框架：基于Python的静态网站生成器
  • 特性：配置简单、构建快速、主题支持
  • 部署：输出静态HTML，可部署至任意平台
  • 插件：丰富的扩展插件生态系统
  • 主题：Material主题、ReadTheDocs主题、自定义主题
  • 适用场景：Python项目、技术文档

Hugo

Hugo

  • Framework: Go-based static site generator
  • Features: Extremely fast builds, flexible content organization
  • Deployment: Static HTML output, deploy anywhere
  • Themes: Extensive theme library
  • Shortcodes: Custom content components
  • Use Cases: Fast documentation sites, multi-language sites
  • 框架：基于Go的静态网站生成器
  • 特性：极速构建、灵活的内容组织
  • 部署：输出静态HTML，可部署至任意平台
  • 主题：丰富的主题库
  • 短代码：自定义内容组件
  • 适用场景：快速文档站点、多语言站点

Jekyll

Jekyll

  • Framework: Ruby-based static site generator
  • Features: GitHub Pages native support, Liquid templating
  • Deployment: GitHub Pages, Netlify, Vercel
  • Plugins: Plugin ecosystem for extensions
  • Theme: Theme support and customization
  • Use Cases: GitHub Pages documentation, simple sites
  • 框架：基于Ruby的静态网站生成器
  • 特性：原生支持GitHub Pages、Liquid模板引擎
  • 部署：GitHub Pages、Netlify、Vercel
  • 插件：用于扩展功能的插件生态系统
  • 主题：主题支持与自定义
  • 适用场景：GitHub Pages文档、简单站点

Documentation Platforms

文档平台

GitBook

GitBook

  • Features: Collaborative editing, version control, search
  • Integration: GitHub/GitLab sync, webhooks
  • Hosting: Managed hosting with custom domains
  • Collaboration: Team collaboration features
  • Use Cases: Team documentation, product docs
  • 特性：协作编辑、版本控制、搜索功能
  • 集成：与GitHub/GitLab同步、Webhooks
  • 托管：支持自定义域名的托管服务
  • 协作：团队协作功能
  • 适用场景：团队文档、产品文档

ReadMe

ReadMe

  • Features: API documentation, developer portal, guides
  • Integration: API sync, custom domains, analytics
  • Hosting: Managed hosting platform
  • Interactive: Interactive API explorer
  • Use Cases: API documentation, developer portals
  • 特性：API文档、开发者门户、指南
  • 集成：API同步、自定义域名、分析功能
  • 托管：托管平台服务
  • 交互性：交互式API探索器
  • 适用场景：API文档、开发者门户

Notion

Notion

  • Features: Rich text editor, database, collaboration
  • Integration: API access, webhooks, embeds
  • Hosting: Managed platform
  • Flexibility: Highly flexible and customizable
  • Use Cases: Internal documentation, knowledge base
  • 特性：富文本编辑器、数据库、协作功能
  • 集成：API访问、Webhooks、嵌入功能
  • 托管：托管平台
  • 灵活性：高度灵活与可定制
  • 适用场景：内部文档、知识库

Confluence

Confluence

  • Features: Wiki-style documentation, collaboration, integration
  • Integration: Jira, Bitbucket, other Atlassian tools
  • Hosting: Self-hosted or cloud
  • Enterprise: Enterprise features and permissions
  • Use Cases: Enterprise documentation, team wikis
  • 特性：Wiki风格文档、协作、集成功能
  • 集成：与Jira、Bitbucket及其他Atlassian工具集成
  • 托管：自托管或云端托管
  • 企业级：企业级特性与权限管理
  • 适用场景：企业文档、团队Wiki

Version Control for Documentation

文档版本控制

Git Workflows

Git工作流

  • Branching Strategy: Feature branches, release branches
  • Commit Messages: Clear, descriptive commit messages
  • Pull Requests: Code review for documentation changes
  • Version Tags: Tag documentation releases
  • Changelog: Track changes between versions
  • 分支策略：功能分支、发布分支
  • 提交信息：清晰、描述性的提交信息
  • 拉取请求：对文档变更进行代码审查
  • 版本标签：为文档版本打标签
  • 变更日志：跟踪版本间的变更

Documentation Versioning

文档版本化

  • Semantic Versioning: Use semantic versioning for docs
  • Version Branches: Maintain documentation for multiple versions
  • Version Selector: UI for switching between versions
  • Deprecation: Mark old versions as deprecated
  • Migration Guides: Help users migrate between versions
  • 语义化版本控制：对文档使用语义化版本控制
  • 版本分支：维护多版本文档
  • 版本选择器：用于切换版本的UI组件
  • 弃用标记：将旧版本标记为已弃用
  • 迁移指南：帮助用户在版本间迁移

Documentation Deployment Workflows

文档部署工作流

CI/CD Integration

CI/CD集成

  • GitHub Actions: Automated builds and deployments
  • GitLab CI: Pipeline-based deployments
  • Jenkins: Custom build and deploy pipelines
  • Netlify: Automatic deployments on git push
  • Vercel: Preview deployments and production builds
  • GitHub Actions：自动化构建与部署
  • GitLab CI：基于流水线的部署
  • Jenkins：自定义构建与部署流水线
  • Netlify：Git推送时自动部署
  • Vercel：预览部署与生产构建

Preview Deployments

预览部署

  • Pull Request Previews: Deploy docs for each PR
  • Staging Environments: Staging environment for testing
  • Review Apps: Temporary review environments
  • URL Sharing: Share preview URLs with reviewers
  • Auto-Cleanup: Automatic cleanup of preview deployments
  • 拉取请求预览：为每个PR部署文档预览
  • 预发布环境：用于测试的预发布环境
  • 评审应用：临时评审环境
  • URL分享：与评审人员分享预览URL
  • 自动清理：自动清理预览部署资源

Production Deployment

生产部署

  • Automated Builds: Build on merge to main branch
  • Deployment Triggers: Manual or automatic deployments
  • Rollback: Ability to rollback to previous versions
  • Monitoring: Monitor deployment status and errors
  • Notifications: Notify team of deployment status
  • 自动化构建：合并至主分支时自动构建
  • 部署触发：手动或自动部署
  • 回滚：回滚至之前版本的能力
  • 监控：监控部署状态与错误
  • 通知：向团队发送部署状态通知

Search Optimization for Documentation

文档搜索优化

SEO Best Practices

SEO最佳实践

  • Meta Tags: Title, description, keywords
  • URL Structure: Clean, descriptive URLs
  • Sitemap: XML sitemap for search engines
  • Robots.txt: Control search engine crawling
  • Schema Markup: Structured data for rich snippets
  • 元标签：标题、描述、关键词
  • URL结构：清晰、描述性的URL
  • 站点地图：供搜索引擎抓取的XML站点地图
  • Robots.txt：控制搜索引擎爬取行为
  • Schema标记：用于富文本片段的结构化数据

Internal Search

内部搜索

  • Search Index: Full-text search index
  • Fuzzy Search: Handle typos and partial matches
  • Faceted Search: Filter by category, tag, version
  • Search Analytics: Track search queries and results
  • Popular Searches: Highlight popular content
  • 搜索索引：全文搜索索引
  • 模糊搜索：处理拼写错误与部分匹配
  • 分面搜索：按分类、标签、版本过滤
  • 搜索分析：跟踪搜索查询与结果
  • 热门搜索：高亮热门内容

External Search

外部搜索

  • Google Custom Search: Integrate Google search
  • Algolia: Powerful search-as-a-service
  • Elasticsearch: Self-hosted search solution
  • Lunr.js: Client-side search for static sites
  • TypeSense: Open source search engine
  • Google自定义搜索：集成Google搜索
  • Algolia：强大的搜索即服务
  • Elasticsearch：自托管搜索解决方案
  • Lunr.js：静态站点的客户端搜索
  • TypeSense：开源搜索引擎

Analytics and Feedback Collection

分析与反馈收集

Documentation Analytics

文档分析

  • Page Views: Track page views and unique visitors
  • Time on Page: Measure engagement and reading time
  • Bounce Rate: Identify pages with high exit rates
  • Search Queries: Track what users are searching for
  • User Flow: Understand user navigation paths
  • 页面浏览量：跟踪页面浏览量与独立访客数
  • 页面停留时间：衡量用户参与度与阅读时长
  • 跳出率：识别高退出率的页面
  • 搜索查询：跟踪用户搜索的内容
  • 用户流：了解用户导航路径

Feedback Collection

反馈收集

  • Feedback Forms: Collect user feedback on pages
  • Ratings: Star ratings or thumbs up/down
  • Comments: Allow comments on documentation
  • Surveys: Periodic user surveys
  • Support Tickets: Track documentation-related support tickets
  • 反馈表单：收集用户对页面的反馈
  • 评分：星级评分或点赞/点踩
  • 评论：允许用户对文档发表评论
  • 调查：定期用户调查
  • 支持工单：跟踪与文档相关的支持工单

Metrics and KPIs

指标与KPI

  • Documentation Coverage: Percentage of features documented
  • Search Success Rate: Percentage of successful searches
  • User Satisfaction: User satisfaction scores
  • Time to Answer: Average time to find answers
  • Support Reduction: Reduction in support tickets
  • 文档覆盖率：已记录功能的百分比
  • 搜索成功率：成功搜索的百分比
  • 用户满意度：用户满意度评分
  • 问题解决时间：用户找到答案的平均时间
  • 支持工单减少率：支持工单的减少幅度