Skip to content

Broken help links in QualCoder 4.0 #1649

Closed

Description

@kaixxx

Describe the bug :


@Salomon-Mazatlan has discovered that we have a few broken help links in QualCoder version 4.0, because pages on the website have been renamed or moved, causing 404 errors.
Affected pages for English:

Broken English URL Source location Replacement
https://qualcoder.org/doc/en/6.2.-AI-Prompt-Editing/ src/qualcoder/ai_prompt_library.py:270 https://qualcoder.org/doc/en/6.3.-AI-Prompt-Library/
https://qualcoder.org/doc/en/4.6-Code-Organiser/ src/qualcoder/information.py:555 https://qualcoder.org/doc/en/4.6.-Code-Organiser/
https://qualcoder.org/doc/en/5.3.-Reports/ src/qualcoder/information.py:577 and :602 https://qualcoder.org/doc/en/5.3.-Analysis/ and https://qualcoder.org/doc/en/5.4.-Reports/
https://qualcoder.org/doc/en/5.4.-Graph/ src/qualcoder/information.py:595 https://qualcoder.org/doc/en/5.5.-Graph/

For English and French, I have already added redirects to the website to fix this. The old Reports URL redirects to a translated legacy landing page linking to both the now split Analysis and Reports pages.
See: QualCoder-Org/qualcoder-org.github.io#91

German and Spanish help pages need updating before we apply the same fixes there. They still have the old structure.

I will work on updating the German help pages.
@Salomon-Mazatlan: Could you take a look at the Spanish pages?
@qwertygc: As always, the French version was perfectly up to date :)

After the help files in all languages have the same structure again, we can update the source code to correct the broken links - or go directly to the new layout with the help button in the bottom left.

Activity

  1. ccbogel commented on Oct 14, 2026

    @ccbogel
    Owner

    Yes go to the new layout with the help button bottom left.
    Maybe no specificity for individual pages, but just help to open the Overview page for each language.

  2. Salomon-Mazatlan commented on Oct 14, 2026

    @Salomon-Mazatlan
    Collaborator

    @Salomon-Mazatlan: Could you take a look at the Spanish pages?

    Yes, I’ll look into it later.

  3. Salomon-Mazatlan commented on Oct 16, 2026

    @Salomon-Mazatlan
    Collaborator

    Hi @kaixxx and @qwertygc

    There is another issue with the help links. In English they work well, including the ones that point to a specific section of the Analysis and Reports pages. In other languages the section anchor is generated from the translated heading, so it changes.

    For example, the help for Code frequencies points to /5.4.-Reports/#code-frequencies-report. In the Spanish docs that heading becomes #frecuencias-de-codigos, so the link opens the Reports page but stays at the top instead of jumping to the section.

    In __main__.py I map each module to its page and section by hand (MODULE_HELP_PAGES, below). Doing the same for every language would mean many more entries, and checking them each time a heading changes in any translation.

    A simpler option would be to give each heading a fixed anchor that is the same in all languages. The docs already use attr_list (the { .md-button } buttons), so this should work without changing the config. In the Spanish file the heading would look like this.

    ## Frecuencias de códigos { #code-frequencies-report }

    Translators would only need to keep the { #... } part as it is, and the app could use the same table for every language. Adding the same id to the English headings would also keep the links working if a heading is renamed. I also thought of numbered anchors like #1, but those would break whenever a section is added or moved.

    What do you think?


    Current MODULE_HELP_PAGES in __main__.py

    # Help pages on qualcoder.org/doc for the modules shown in the main tabs
    MODULE_HELP_PAGES = {
        # Manage
        "DialogManageFiles": "3.2.-Files/",
        "DialogManageLinks": "3.2.-Files/#manage-bad-links-to-files",
        "DialogCases": "3.3.-Cases/",
        "DialogManageAttributes": "3.4.-Attributes/",
        "DialogReferenceManager": "3.5.-References/",
        "DialogImportSurvey": "6.2.-Survey-Imports/",
        # Coding
        "DialogCodeText": "4.1.-Coding-Text/",
        "DialogCodePdf": "4.3.-Coding-Text-on-PDFs/",
        "DialogCodeImage": "4.4.-Coding-Images/",
        "DialogCodeAV": "4.5.-Coding-Audio-and-Video/",
        "CodeOrganiser": "4.6.-Code-Organiser/",
        "DialogCodeColorScheme": "4.7.-Codes-Tree/#accessibility-and-code-colours",
        # Analysis menu
        "DialogReportCodes": "5.3.-Analysis/#code-retrieval",
        "DialogReportCooccurrence": "5.3.-Analysis/#code-co-occurrence-report",
        "DialogReportRelations": "5.3.-Analysis/#code-relations-report",
        "DialogReportExactTextMatches": "5.3.-Analysis/#code-text-by-exact-matches-report",
        "DialogCodesBySegments": "5.3.-Analysis/#codes-by-text-segments-report",
        "ViewGraph": "5.5.-Graph/",
        # Reports menu
        "DialogReportCoderComparisons": "5.4.-Reports/#coding-comparison-report",
        "DialogCompareCoderByFile": "5.4.-Reports/#coding-comparison-by-file-report",
        "DialogReportComparisonTable": "5.4.-Reports/",
        "DialogReportCodeFrequencies": "5.4.-Reports/#code-frequencies-report",
        "DialogReportFileSummary": "5.4.-Reports/#file-summary-report",
        "DialogReportCodeSummary": "5.4.-Reports/#code-summary-report",
        "ViewCharts": "5.4.-Reports/#charts",
        "DialogSQL": "5.4.-Reports/#database-queries",
        # AI
        "DialogAIChat": "5.1.-AI-chat-based-analysis/",
    }
    AI_ASSISTED_CODING_HELP_PAGE = "4.2.-AI-Assisted-Coding/"
    
  4. qwertygc commented on Oct 16, 2026

    @qwertygc
    Collaborator

    Good idea, and helping translation. I just need to see files to change.

  5. qwertygc commented on Oct 16, 2026

    @qwertygc
    Collaborator

    OK fixed for FR doc.

  6. Salomon-Mazatlan commented on Oct 17, 2026

    @Salomon-Mazatlan
    Collaborator

    6. OK fixed for FR doc.

    Could you please add them to the English files?

    It may seem redundant, but they’re the basis for many of the other translations, and they’d also help if a module ever gets renamed.

    This Saturday or Sunday I’ll make the adjustments in the software and do the Spanish translations.

  7. ccbogel commented on Oct 17, 2026

    @ccbogel
    Owner
  8. kaixxx commented on Oct 19, 2026

    @kaixxx
    CollaboratorAuthor

    I have updated the German analysis and reports anchors as well.

  9. qwertygc commented on Oct 19, 2026

    @qwertygc
    Collaborator

    Updated PT

  10. Salomon-Mazatlan commented on Oct 29, 2026

    @Salomon-Mazatlan
    Collaborator

    Could we close this issue?

  11. ccbogel commented on Oct 30, 2026

    @ccbogel
    Owner

    sure

  12. kaixxx commented on Oct 30, 2026

    @kaixxx
    CollaboratorAuthor

    Could we close this issue?

    Did you update the Spanish help pages? In this case, we need to also include Spanish into the help redirects on the website, so that the links in QualCoder 4.0 go to the correct pages (e.g., Analysis and Reports).

  13. Salomon-Mazatlan commented on Nov 2, 2026

    @Salomon-Mazatlan
    Collaborator

    Did you update the Spanish help pages? In this case, we need to also include Spanish into the help redirects on the website, so that the links in QualCoder 4.0 go to the correct pages (e.g., Analysis and Reports).

    Hi @kaixxx & @qwertygc , I had forgotten to update zensical. I sent PR QualCoder-Org/qualcoder-org.github.io#100 with the changes.

    I opened it as a PR so you can check whether the changes are correct.

  14. qwertygc commented on Nov 2, 2026

    @qwertygc
    Collaborator

    It's work.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions