Strategic Refactor: Establish Persona-Based Documentation Paths
Évaluation
- Difficulté
- 5/5
- Temps estimé
- Plus d'une semaine
- Accessibilité débutants
- 35/100
- Type d'issue
- Documentation
- Clarté
- Plutôt claire
- Activité
- Calme
- Stack technique
- markdown
- Domaine
- documentation
Piste de recherche
Commencez par examiner la PR #249 et les résultats du sondage Slack référencés dans l’issue. Auditez la documentation existante en .rst et .md, en attribuant à chaque fichier la persona Legal/Compliance, Security/SCA ou Dev/Integrators. La tâche sera considérée comme terminée lorsque vous aurez fourni la cartographie du contenu avec les tags, une proposition d’arborescence de site Sphinx et des documents de parcours utilisateur pour au moins deux rôles.
Rédigé par le modèle d'indexation à partir du texte de l'issue.
Description
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.
- Langage dominant
- Batchfile
- Étoiles
- 310
- Forks
- 255
- Merge moyen
- 10 h 5 min
- PR mergées (30 j)
- 1
Préparer son environnement
- Aucun Dockerfile ni fichier Docker Compose
- Propose un modèle de pull request
- Lire le guide de contribution
Par où commencer
- Lisez l'issue en entier, puis le guide de contribution du projet.
- Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
- Forkez le dépôt et travaillez sur une branche.
- Ouvrez une pull request qui référence le numéro de l'issue.
Autres issues de aboutcode-org/aboutcode
-
Cross-reference OpenChain CRA Compliance ChecklistPeut-être à nouveau libre @PaulitePavitra l’a pris il y a 20 jours, et aucune pull request n’est ouverte. Ouverte
Difficulté 2/5 1-3 heures Accessibilité débutants 68/100
aboutcode-org/aboutcode#309 · 6 commentaires ·
-
Difficulté 5/5 Plus d'une semaine Accessibilité débutants 30/100
aboutcode-org/aboutcode#314 · 4 commentaires ·
-
Project: 5C: Continuous Code Compliance Control CenterPeut-être à nouveau libre @nt5504289-oss l’a pris il y a 32 jours, et aucune pull request n’est ouverte. Ouverte
Difficulté 5/5 Plus d'une semaine Accessibilité débutants 15/100
aboutcode-org/aboutcode#291 · 3 commentaires ·
-
Remove Projects section in READMEPeut-être pris @mjherzog l’a pris il y a 244 jours. Ouvertedocumentation
aboutcode-org/aboutcode#277 · 6 commentaires · 1 personne assignée ·
-
RFC: Create AI policyPeut-être à nouveau libre @tdruez l’a pris il y a 252 jours, et aucune pull request n’est ouverte. Ouvertepolicy
aboutcode-org/aboutcode#265 · 10 commentaires · 1 personne assignée ·
Toutes les issues de aboutcode-org/aboutcode
Issues similaires
-
app: scripts status: backlog type: documentation
Difficulté 2/5 1-3 heures Accessibilité débutants 86/100
netbox-community/netbox-scripts#68 ·
Les mainteneurs répondent en général sous 1 jour
-
Difficulté 1/5 Moins d'une heure Accessibilité débutants 91/100
marin-community/marin#10765 ·
Les mainteneurs répondent en général sous 1 jour
-
Dokumentasjon på nais defaultsOuverte
Difficulté 2/5 1-3 heures Accessibilité débutants 72/100
Les mainteneurs répondent en général sous 1 jour
-
Difficulté 1/5 Moins d'une heure Accessibilité débutants 67/100
-
documentation good first issue help wanted
Difficulté 2/5 1-3 heures Accessibilité débutants 64/100
dev-five-git/devup-ui#876 ·
Les mainteneurs répondent en général sous 11 jours