Strategic Refactor: Establish Persona-Based Documentation Paths

Open
#250 11 comments 0 reactions 0 assignees View on GitHub

@IQRAZAM is already working on this.

Since Feb 21, 2026.

  • #260 by @gyanranjanpanda — open

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Quiet
Tech stack
markdown
Domain
documentation

Research direction

Start by reviewing PR #249 and the Slack poll results referenced in the issue. Audit the existing .rst and .md documentation, tagging each file by the Legal/Compliance, Security/SCA, or Dev/Integrators persona. Done means providing the tagged content map, a proposed Sphinx site map, and user-journey documents for at least two roles.

Written by the indexing model from the issue text.

Description

documentation

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.

Dominant language
Batchfile
Stars
316
Forks
257
PR merge metrics
No merged PRs in 30d

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from aboutcode-org/aboutcode

All issues in aboutcode-org/aboutcode

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.