Strategic Refactor: Establish Persona-Based Documentation Paths

[cannonerd007]

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.

[cannonerd007]

@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]

Hii @cannonerd007 are looking for any contributors i would like to work with you

[NotIbutme]

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]

hi @cannonerd007 If nobody has solved it yet i would love to fix this documentation .Let me know if i should do it.
Thanks

[Siddhazntx]

is this still open to work on ?

[AyachiMishra]

can i work on this? i have read adn understoff the full documentation

[Siddiquiashrafhussain]

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]

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]

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:

1. Audit existing documentation files (docs/source/), including contributing/, getting-started/, aboutcode-project/, archive/, etc., to ensure they are properly mapped to the relevant user personas.

2. Identify gaps or opportunities in content coverage for each persona.

3. Draft additional user journeys for roles that may not yet be fully covered (e.g., first-time Compliance Officer, Security researcher workflows).

4. 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]

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!