Skip to content

docs: put what readers come for at the top of six heavily skimmed pages - #16327

Merged
Maffooch merged 8 commits into
DefectDojo:devfrom
devGregA:devgrega/docs-heatmap-reading-order
Oct 19, 2026
Merged

Maffooch merged 8 commits into
DefectDojo:devfrom
devGregA:devgrega/docs-heatmap-reading-order

Conversation

@devGregA

Copy link
Copy Markdown
Contributor

Summary

Six docs pages lose half of their desktop readers early, based on the last 30 days of visitor heatmaps. This PR puts the tasks those readers come for near the top. Every change adds text or moves existing sections. Nothing is deleted and no facts change. Only the English files are edited. Translations are regenerated after the English is approved.

Introduction to Findings (triage_findings/findings_workflows/intro_to_findings.md)
Half of readers leave before 22% of the page. Of the sections further down, Example Finding Workflows got the most reading time, and the Notes section above it got the least. Added a short opener that links to triage statuses, Risk Acceptances and Creating Findings Manually. Moved Example Finding Workflows above Notes and @mentions.

Assets, Open Source (asset_modelling/engagements_tests/OS__assets.md)
Half of readers leave before 17%, and about 60% of reading time lands on the overview and examples. Asset Boundaries is the most clicked table of contents entry. Added a short opener that says what an Asset is and links to the scoping and create sections. Moved Asset Boundaries up next to Asset Examples so the scoping guidance sits in one place.

About DefectDojo (get_started/about/about_defectdojo.md)
Half of readers leave before 25%. The most clicked items on the page are the demo password, the demo links and the Installation and Feature comparison links in the sidebar. Added a short opener linking to the online demos, the Open-Source and Pro install guides, and the feature comparison. Moved Online Demos up so it follows What is DefectDojo.

Asset Hierarchy: Overview, Open Source (asset_modelling/OS_hierarchy/OS__asset_hierarchy.md)
Half of readers leave before 32%. Most rage clicks land on the "What can an Organization/Asset represent?" text. Added a two paragraph summary of the five levels, restating what the page already says about each one and about access control and deduplication scope. It links to the three "What can ... represent?" sections.

Reimport (import_data/import_intro/reimport.md)
Half of readers leave before 27%. Clicks cluster on the paragraph about ignoring existing Findings, the close and reactivate settings, and the Reimport Deduplication paragraph near the bottom. Added a short opener naming the four Reimport outcomes, with links to Reimport Logic, Reimport Deduplication and Opening the Reimport form. Moved Reimport Deduplication to directly after Reimport Logic. In the moved paragraph, a pair of em dashes became parentheses.

Pro Kubernetes / Helm install guide (get_started/pro/onprem/kubernetes/installing_on_kubernetes.md)
This page is about 72 screens long. 21% of visits scroll back and forth four or more times, and the median scroll depth is 11%. Clicks go to the global.imageRegistry values, the license-to-registry login pipeline, helm registry login and the private registry paragraph. Added a Quick Path ordered list near the top that links to the existing install sections in order. It also links to registry login, private registry mirroring, known issues and troubleshooting. No sections were moved. This page is generated from the DefectDojo Pro Helm chart repository, so the same Quick Path has to go into that repository's docs/INSTALLATION_GUIDE.md. Otherwise the next sync overwrites it.

🤖 Generated with Claude Code

devGregA and others added 6 commits October 13, 2026 19:22
Add a short opener that links to the triage, risk acceptance and manual creation tasks, and move Example Finding Workflows above the Notes section. No content removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s (OS)

Add a short opener and move Asset Boundaries up next to Asset Examples so the scoping guidance sits together. No content removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Add a short opener linking to the online demos, installation guides and feature comparison, and move Online Demos up under What is DefectDojo. No content removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Add a two paragraph summary of Organizations, Assets, Engagements, Tests and Findings, restating facts already on the page, with links to the planning sections. No content removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ation up

Add a short opener naming the four Reimport outcomes with links, and move Reimport Deduplication directly after the Reimport Logic section. The moved paragraph swaps an em dash pair for parentheses. No content removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Add an ordered Quick Path near the top linking to the existing install sections, plus links to registry login, private registry mirroring, known issues and troubleshooting. This page is generated from the Pro Helm chart repository, so the same change has to land in its docs/INSTALLATION_GUIDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@devGregA devGregA added this to the 3.4.200 milestone Oct 14, 2026
@github-actions github-actions Bot added the docs label Oct 14, 2026
@devGregA
devGregA marked this pull request as ready for review October 14, 2026 03:38
@github-actions

Copy link
Copy Markdown
Contributor

This pull request has conflicts, please resolve those before we can evaluate the pull request.

…reading-order

# Conflicts:
#	docs/content/import_data/import_intro/reimport.md
@github-actions

Copy link
Copy Markdown
Contributor

Conflicts have been resolved. A maintainer will review the pull request shortly.

@Maffooch
Maffooch added this pull request to the merge queue Oct 19, 2026
Merged via the queue into DefectDojo:dev with commit 87bddc9 Oct 19, 2026
31 checks passed
@Maffooch
Maffooch deleted the devgrega/docs-heatmap-reading-order branch October 19, 2026 16:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants