django/djangoproject.com

Docs for old supported versions should indicate that a newer version is available

Open

#1,122 opened on Nov 15, 2021

View on GitHub
 (8 comments) (3 reactions) (0 assignees)Python (2,001 stars) (1,100 forks)user submission
docsgood first issuenew feature

Description

I ended up on the Django 2.2 version of the "Writing your first app" tutorial via web search, and didn't realize I was looking at outdated docs until I noticed the URL a few pages in. I realize that 2.2 is still getting extended support, but regardless this probably isn't the version of the tutorial that most people want, and the design of the page gives no indication that you're not looking at the latest version. Completely unsupported docs like those for 1.8 have a helpful banner at the top of the page indicating that the version isn't supported. I'm not saying a big scary red banner is necessary for old versions that are still supported, but some indication that there are newer versions would be nice.

This is a problem that a lot of projects face and solve in different ways - some examples below.

  • Postgres has a prominent version switcher at the top of every docs page indicating what versions are supported, plus a warning when you're looking at an unsupported version:

Postgres docs version switcher

  • Docs sites that use Read The Docs have a nice little "there is a newer version available" note at the top of outdated pages: Requests outdated version indicator

standard RTD newer version indicator (csvkit)

  • CockroachDB provides an explicit warning on docs for old versions to indicate when they will stop being supported: CockroachDB support warning

Contributor guide

Tech stack
pythonhtmlcssjavascript
Domain
documentationdesign
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
basic knowledge of Django templatesHTML/CSSfamiliarity with djangoproject.com repository
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
90
Research direction
The issue asks for a visible indicator on documentation pages for still supported older versions (e.g., Django 2.2) that a newer version is available. The current unsupported version pages have a red banner (see issue for link). To implement, examine the template where the unsupported banner is added (likely in the base template under `djangoproject.com/djangoproject/templates/`). Look for a template tag or context variable that tracks the version. Then add a similar but less severe banner for supported but outdated versions. The maintainers have not commented on implementation details, but the issue includes examples from Postgres and ReadTheDocs. No linked PRs exist. Start by identifying the template that renders version specific banners and propose a change to add a conditional message.