Repository navigation
Strategic Refactor: Establish Persona-Based Documentation Paths #250
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 docs: define core user roles and personas for community research #249 to ensure the reorganization is data-driven.
Activity
cannonerd007 commentedon Jan 26, 2026
@DennisClark I am very interested in leading this documentation refactor! Since I am already working on the persona research in PR #249, I have the best context to execute this. Could you please assign this issue to me?
I plan to start mapping the documentation paths as soon as we get the first round of data from the Slack poll.
Subhrasameerdash commentedon Jan 28, 2026
Hii @cannonerd007 are looking for any contributors i would like to work with you
NotIbutme commentedon Jan 31, 2026
Hi @cannonerd007 This sounds like a really impactful documentation improvement .
I’d be happy to help with clearly scoped pieces such as: Auditing existing .rst/.md files and tagging them by target persona ,
Helping draft a user journey (e.g. first-time Compliance Officer) , Reviewing introductory docs for jargon and language clarity .
OmAmbole009 commentedon Feb 4, 2026
hi @cannonerd007 If nobody has solved it yet i would love to fix this documentation .Let me know if i should do it.
Thanks
docs: implement persona-based documentation paths
docs: implement persona-based documentation paths
Siddhazntx commentedon Feb 5, 2026
is this still open to work on ?
AyachiMishra commentedon Feb 6, 2026
can i work on this? i have read adn understoff the full documentation
Siddiquiashrafhussain commentedon Feb 7, 2026
Hi there! I’m interested in working on this issue. Is it still open? Please let me know if I can take it up.
krishnavasnani07 commentedon Feb 20, 2026
Hi 👋
I’m interested in working on this issue as part of my open-source contributions (and potential GSoC preparation).
I’ve gone through the discussion and codebase, and I believe I can handle this task.
If this issue is unassigned, may I be assigned to it?
If you have any guidance, expectations, or preferred approach before I start, I’d really appreciate it.
Thanks!
IQRAZAM commentedon Feb 21, 2026
Hi @DennisClark
I’d like to contribute to the persona-based documentation issue (#250) .
After reviewing the repository and the recent updates, I see that the main persona landing pages and homepage updates have been implemented. To complement this work, my proposed approach is:
Audit existing documentation files (
docs/source/), includingcontributing/,getting-started/,aboutcode-project/,archive/, etc., to ensure they are properly mapped to the relevant user personas.Identify gaps or opportunities in content coverage for each persona.
Draft additional user journeys for roles that may not yet be fully covered (e.g., first-time Compliance Officer, Security researcher workflows).
Review pages for clarity and accessibility, suggesting improvements where technical jargon might be challenging for non-technical personas.
This work is additive and complementary to the recent persona landing pages, aiming to make the documentation more complete and user-friendly.
If this issue is still open, I’d be happy to take it on and contribute. Could you please assign me to it?
Thanks for your guidance!
zeba-source commentedon Feb 24, 2026
Hi @DennisClark , I am interested in working on this issue as I have been working on previous issues of about code I am familiar with the code base and the flow . If you have any guidance, expectations, or preferred approach before I start, I’d really appreciate it.
Thanks!
huda-code commentedon May 7, 2026
Hi @cannonerd007, I’d be interested in contributing to this issue if collaboration is still open.
I’ve worked across AI systems, cybersecurity, developer tooling, and non-technical stakeholder communication, so the persona-based documentation direction here is very interesting to me.
I’d specifically be interested in helping with:
I also noticed there are no active PRs currently linked to continue the broader refactor, so I’d be happy to help with scoped documentation audits or persona journey docs if useful.
Thanks!