How to handle linking to changelog and version hints in main docs

Archive Documentation
1

When updating the main docs based on the changelogs we can have these 2 extremes:

  1. Just change main docs, as soon as something gets deprecated, remove it, do not mention old way, do not link to changelog
  2. Explain the change, mention since when it was changed (e.g. since version 10.2) and (optionally) link to changelog. Remove the note and the link 1 versions later (e.g. if deprecated in 8 and removed in 9, note can be removed in 10).

The first way is the most maintainer-friendly and efficient. The change must be made only once. But it is the most user-unfriendly, because there is a sudden change with no explanation. Users are forced to read all changelogs, to stay up to date about what changed.

The second is the most maintainer-unfriendly: Changes must be made often more than once, e.g. (first= point out deprecation or new feature, add version hint, possibly link to changelog and then (later) remove this - e.g. 1 oder 2 versions later. But, the user gets more context, he / she gets a reminder that something changed, if lucky they even find a link to the changelog so they can read up about why it got changed.

The policy was changed at least once. Previously, we used 1. - without notes. For a while now, we have been adding the notes to explain the changes. The official docs explain the version hints and link to changelog (3 and 4): Documentation content style guide — Writing Documentation main documentation

But, we never really decided about this officially.

So, what should we do now?

Pro 1: no hints, links, explanation

  • less work for people updating based on changelogs
  • “cleaner” docs, the hints and notes makes docs look “cluttered”
  • This is information only relevant if you are moving to a new version. This should not be in the main docs.
  • if the version hints are used, it is sometimes unclear if this refers only to a section or to entire page.

Pro 2: version hints, explanation, links to changelog

  • user gets more context
  • user is reminded that something has changed

Examples:

2

Changelog Links

I’d start by distinguishing by type:

Features:
The feature rst should become part of the official docs and does not provide additional information or context for a user after that → do not link to it.

Deprecations/Breaking Changes:
The Changelog items describe the migration, here I see two choices

  • keep the Changelog as kind of “Upgrade guide”
  • Integrate the Migration instructions / Changelogs with Migrations into the Upgrade Guide per Version

No matter where the content ends up, I would link that ideally always at the bottom of a section (so it doesn’t clutter) in a box that looks the same everywhere (“Migration Hints” or something) → A bit like the further reading links on the Symfony docs.

Version Hints

I would keep it to one version displayed to avoid cluttering the documentation:

  • In References we could add the version where something was introduced (because that’s mostly 1:1 connection)
  • In Guides I would probably not add version hints (because it adds a lot of noise, as the Symfony Command link has shown) and rely on the version switcher providing accurate information per selected version.
3
  1. Link either to changelog or Feature.rst.

We used that in a project and it was considered very helpful by the users.

If we stick to the versionadded / versionremoved and changed notation from sphinx we can also auto find / remove old records.

4

Working a log with Gitlab, I found it very helpful there to have a “Introduced in version x” at the top of a section. Now Gitlab brings out a new minor version every month and this feature is not to be applied 1:1 but maybe it can help as a source of inspiration.

All in all, having documentation by version is definitely the right way to go further on, maybe what we need as new chapter for each version should be “Migrations”, as seen in PHP documentation, too, for example.