Update external resource in the documentation

I was wondering how to submit correction in the documentation. The wikipedia resource linked at this section for AEAD should be replaced with a current version: https://en.wikipedia.org/wiki/Authenticated_encryption

1 Like

Hi! I created https://jira.mongodb.org/browse/DOCS-14536 for this issue.

2 Likes

Hi @Student_al_St,

Thank for you for the feedback! It seems unusual that the documentation is linking to a specific version of this Wikipedia article rather than the canonical link for the latest version, but I found a few similar references which should be corrected.

The MongoDB manual includes an About MongoDB Documentation reference with more information on reporting issues and making change requests, but the TL;DR is:

Regards,
Stennie

Great!!
I wasn’t aware that one could submit a PR given that I looked though some links where it would explicitly say “Edit this Page in GitHub” thus one would just click that and submit a PR. May be something to add in each page of the documentation? This would just be a footer note update.

Thank you for the info, though.

Alain.

1 Like

Hi Alain,

We used to have “edit on GitHub” links on most documentation pages but it isn’t always straightforward to figure out how to make a change. The mapping of pages to source files often isn’t 1:1 because pages can be built with shared blocks of content, and some changes require building a preview version of the documentation for review.

The strong preference is to have tracking issues in Jira to help triage and organise issues. A single change to the latest version of the server documentation (eg 4.4) may be applicable to multiple server release versions and end up ported with PRs to each non end-of-life docs release (currently 5.0, 4.4, 4.2, and 4.0). The DOCS issue is a common reference for these PRs.

I ended up raising a PR for DOCS-14536 which has been merged into the MongoDB 5.0 manual. Since this is a minor change, I don’t think it needs to be backported to older versions of the documentation.

In the process I found a mix of versioned & latest Wikipedia links in the server manual, and updated these to the latest links in my PR for consistency. One of our docs leads mentioned the rationale for using versioned Wikipedia links was to try to ensure destination links remained accurate & relevant. Revisions to Wikipedia articles may alter the page links or content that we expected to be linking to, but versioned links would not be affected. For example, the Wikipedia link to AEAD is a named anchor that relies on the title of the section remaining “Authenticated encryption with associated data (AEAD)”. If the section title changes in a newer revision of the page, the link will still lead to the expected article but without focusing on the referenced section. However, since we previously had mixed usage (more often to the “latest” version of articles) my PR was approved and we are now consistently linking to the latest article versions.

Regards,
Stennie

This topic was automatically closed 5 days after the last reply. New replies are no longer allowed.