Strategic Refactor: Establish Persona-Based Documentation Paths
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
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
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from aboutcode-org/aboutcode
-
Cross-reference OpenChain CRA Compliance ChecklistMay be free again @PaulitePavitra claimed this 41 days ago, and no pull request is open. Open
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
aboutcode-org/aboutcode#309 · 6 comments ·
-
scancode-next: Plan federated software supply chain data infrastructurePossibly taken @ziadhany claimed this 6 days ago. Openmaintainers-only
Difficulty 4/5 3-5 days Newbie friendliness 45/100
aboutcode-org/aboutcode#325 · 2 comments · 2 assignees ·
-
scancode-next: Improve documentation, review documentation issues and pull requestsPossibly taken @hesa claimed this 8 days ago. Openmaintainers-only
aboutcode-org/aboutcode#324 · 1 assignee ·
-
scancode-next: Gather requirements through interviews with key usersPossibly taken @hesa claimed this 8 days ago. Openmaintainers-only
Difficulty 5/5 Over a week Newbie friendliness 25/100
aboutcode-org/aboutcode#323 · 1 assignee ·
-
scancode-next: Prepare ScanCode and AboutCode workshopsPossibly taken @adaaaam claimed this 6 days ago. Openmaintainers-only
aboutcode-org/aboutcode#322 · 1 assignee ·
All issues in aboutcode-org/aboutcode
Similar issues
-
Difficulty 1/5 Under an hour Newbie friendliness 78/100
firefly-iii/firefly-iii#13259 · 3 comments ·
Maintainers usually reply within 1 day
-
documentation
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
molgenis/molgenis-emx2#7059 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
-
[DOCS/SMU] Correct the 1 GiB window bullet and the coverage-target sentence in the SMU datasheetOpenDOCS SMU
Difficulty 2/5 1-3 hours Newbie friendliness 77/100
tenstorrent/tt-oca-harness#3931 ·
Maintainers usually reply within 1 day
-
[Sync EN] Document the getLastErrors() return value change in the PHP 8.2 migration guide (#6107)Opensync-en
Difficulty 1/5 Under an hour Newbie friendliness 78/100
Maintainers usually reply within 1 day