What to do about old versions of the docs on readthedocs?

[nicoddemus]

Yeah recently we had a few cases of misunderstandings because of old links.

Usually we only really keep two docs up-to-date, which is stable and latest.

What should we do with old documentation pages?

Btw the docs mentioned in the original issue are quite old, from the reorganize-docs branch, back in 2016. I don't think we will really pick it up again at this point, perhaps we can just delete them to avoid confusion? @pfctdayelise @hackebrot?

Originally posted by @nicoddemus in #8094 (comment)

[pfctdayelise]

Good idea to avoid confusion, thanks @nicoddemus !

[RonnyPfannschmidt]

btw, do we still have the notes from back then, i believe we should try to make what we set out back in the sprint possible in a more iterative small pieced fashion

[pfctdayelise]

Hmm...the broad idea I believe was to rearrange the docs to distinguish between

• Tutorial
• How-to guide
• Discussions
• Reference

This is described by Daniel Procida in a talk https://pyvideo.org/pycon-au-2017/what-nobody-tells-you-about-documentation.html (although apparently that was 2017, so maybe my brain just made this up....)

Our notes about it are here https://github.com/pytest-dev/pytest/wiki/Docs-refactor , where we didn't mention that, so maybe we were just planning to organise a bit and categorise according to level of user. I do think the docs are still a bit overwhelming and there is not that much navigation help. The reference material has improved a bit though :) not sure if it is complete yet!

There is also a picture of our sticky notes for planned organisation, in the blog post - https://blog.pytest.org/2016/pytest-development-sprint/

[aklajnert]

Since the users are redirected to the old docs from Google, maybe instead of removing them, it would be a good idea to redirect to the new one or display a huge banner, that these docs are for the old version with a link to the new one?

[nicoddemus]

Since the users are redirected to the old docs from Google, maybe instead of removing them, it would be a good idea to redirect to the new one or display a huge banner, that these docs are for the old version with a link to the new one?

Indeed that's ideal, however that setting is already configured:

Perhaps the banner is not showing up because of our theme?

EDIT:

Hold on, actually the banner shows up: https://docs.pytest.org/en/6.0.0/reference.html

however it doesn't show for the link in the original issue: https://docs.pytest.org/en/reorganize-docs/new-docs/user/naming_conventions.html. I also can't find a reorganize-docs version in readthedocs at all:

https://readthedocs.org/projects/pytest/versions/

I suspect the docs for the reorganize-docs branch are still present in the old docs server... does that make sense?

[Zac-HD]

For Hypothesis, we only host "latest", specificially so that stale docs can't show up in search results etc., and I'd support "only stable, latest, and 4.x" for pytest for the same reasons.

(we're also hosting the last py2 docs for now, but free support only applies to the latest release and nobody pays, so 🤷‍♂️)

[nicoddemus]

I'd support "only stable, latest, and 4.x" for pytest for the same reasons.

👍 from me. Does anybody see a good reason to host other versions?

[asottile]

I'd support "only stable, latest, and 4.x" for pytest for the same reasons.

👍 from me. Does anybody see a good reason to host other versions?

sg2m!

[Zac-HD]

Sounds like all we need is for someone with edit access (e.g. @nicoddemus, @pfctdayelise, @RonnyPfannschmidt, @asottile) to go to https://readthedocs.org/projects/pytest/versions/ while logged in, then edit -> uncheck active -> save for all the older versions. I'd be happy to but don't have write access.

[asottile]

whew that was a lot of clicking -- but I think it's done

[Zac-HD]

🎉