aboutcode-org / aboutcode-org/aboutcode

Strategic Refactor: Establish Persona-Based Documentation Paths

Abierto
#250 11 comentarios 0 reacciones 0 asignados Ver en GitHub
documentation
Lenguaje dominante
Batchfile
Estrellas
302
Forks
249
Merge medio
1 d 9 h
PR fusionados (30 d)
2

Descripción

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.

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.