Strategic Refactor: Establish Persona-Based Documentation Paths
评估
- 难度
- 5/5
- 预计耗时
- 一周以上
- 新手友好度
- 35/100
- Issue 类型
- 文档
- 描述清晰度
- 基本清楚
- 活跃度
- 冷清
- 技术栈
- markdown
调研方向
首先审查 PR #249 以及 issue 中引用的 Slack 投票结果。审核现有的 .rst 和 .md 文档，并根据 Legal/Compliance、Security/SCA 或 Dev/Integrators persona 为每个文件添加标签。完成标准是提供已标记的内容映射、拟议的 Sphinx 站点地图，以及至少两个角色的用户旅程文档。
由索引模型根据 Issue 内容生成。
描述
Problem Statement: Currently, the AboutCode documentation is structured primarily around tool functionality. However, our ongoing research into User Roles (see PR #249) indicates that our audience is split between highly technical developers, legal compliance officers, and security researchers. Each of these groups has different "information hunger" and entry points.
Proposal: Conduct a comprehensive audit of the existing documentation to map current content against the newly defined personas:
-
Legal/Compliance: High-level summaries, license policy guides, and reporting features.
-
Security/SCA: Vulnerability database integration and scanning workflows.
-
Dev/Integrators: CLI usage, API documentation, and CI/CD pipeline integration.
-
Goals:
- Identify Gaps: Determine which roles are currently underserved by the documentation.
- Navigation Overhaul: Propose a "Choose Your Own Adventure" style landing page for docs.aboutcode.org.
- Language Consistency: Ensure that non-technical roles aren't hit with jargon in the introductory sections.
-
Acceptance Criteria:
- A spreadsheet or map of existing .rst/.md files tagged by target persona.
- A proposed new Site Map for the Sphinx documentation.
- A "User Journey" document for at least two primary roles (e.g., a first-time Compliance Officer vs. a Senior DevOps Engineer).
-
Additional Context: This issue will directly consume the results of the Slack poll initiated in #249 to ensure the reorganization is data-driven.
- 主要语言
- Batchfile
- 星标
- 310
- 派生
- 255
- 平均合并
- 10 小时 5 分钟
- 30 天内合并 PR
- 1
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue，再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库，在一个分支上完成修改。
- 提交 Pull Request，并在描述里引用这个 Issue 编号。
aboutcode-org/aboutcode 的其他 Issue
-
Cross-reference OpenChain CRA Compliance Checklist可能重新可做 @PaulitePavitra 于 21 天前认领，目前没有进行中的 PR。 未关闭
难度 2/5 1-3 小时 新手友好度 68/100
aboutcode-org/aboutcode#309 · 6 条评论 ·
-
难度 5/5 一周以上 新手友好度 30/100
aboutcode-org/aboutcode#314 · 4 条评论 ·
-
Project: 5C: Continuous Code Compliance Control Center可能重新可做 @nt5504289-oss 于 33 天前认领，目前没有进行中的 PR。 未关闭
难度 5/5 一周以上 新手友好度 15/100
aboutcode-org/aboutcode#291 · 3 条评论 ·
-
Remove Projects section in README可能已有人在做 @mjherzog 于 245 天前认领。 未关闭documentation
aboutcode-org/aboutcode#277 · 6 条评论 · 已指派 1 人 ·
-
RFC: Create AI policy可能重新可做 @tdruez 于 252 天前认领，目前没有进行中的 PR。 未关闭policy
aboutcode-org/aboutcode#265 · 10 条评论 · 已指派 1 人 ·
查看 aboutcode-org/aboutcode 的全部 Issue
相似的 Issue
-
sync-en
难度 2/5 1-3 小时 新手友好度 72/100
维护者通常 1 天内回复
-
难度 1/5 1 小时以内 新手友好度 78/100
维护者通常 1 天内回复
-
enhancement
难度 1/5 1 小时以内 新手友好度 86/100
维护者通常 1 天内回复
-
Support .aac audio uploads可能已有人在做 @julien731 今天认领。 未关闭feature
难度 2/5 1-3 小时 新手友好度 78/100
nimblehq/audio-transcriber#153 ·
-
[DOCS]: enforce_admins description understates what it covers and omits push restrictions可能已有人在做 @dav-tb 今天认领。 未关闭
难度 1/5 1 小时以内 新手友好度 78/100
integrations/terraform-provider-github#3707 · 1 条评论 ·
维护者通常 1 天内回复