django / django/djangoproject.com

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

Open
#1,122 10 comments 3 reactions 0 assignees View on GitHub
docs good first issue new feature
Dominant language
Python
Stars
2k
Forks
1.1k
Avg merge
2d 7h
Merged PRs (30d)
26

Description

I ended up on the [Django 2.2 version](https://docs.djangoproject.com/en/2.2/intro/tutorial01/) 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](https://www.djangoproject.com/download/#supported-versions), 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](https://docs.djangoproject.com/en/1.8/intro/tutorial01/) 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.

Examples of how other projects deal with this

- 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](https://user-images.githubusercontent.com/60245/141797050-65652eb3-a861-46e1-8a89-5b8a023191da.png)

- 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](https://user-images.githubusercontent.com/60245/141797183-589d93df-2833-4f5a-8ae0-e749ec0832ee.png)

![standard RTD newer version indicator (csvkit)](https://user-images.githubusercontent.com/60245/141797394-f61901b3-6292-41b8-96a9-cda1b230a799.png)

- CockroachDB provides an explicit warning on docs for old versions to indicate when they will stop being supported:
![CockroachDB support warning](https://user-images.githubusercontent.com/60245/141798057-68c6dc79-d775-4dc6-a9dc-770035fa6352.png)

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.