[DONE] Handle Changelog vs main documentation (for features)

Archive Documentation
1

How to deal with Changelog becoming main documentation for some new features, duplicate information in changelog & main docs and how to deal with links from / to changelog.

Motivation

IMHO the usage of the changelogs is a huge success:

  • features can be documented along with the changes
  • you often see complete documentation in the changelog for a new feature - perfect!
  • you can view the changelogs in the backend
  • changelog is used in exension scanner

But, there are also problems or rather things that must be decided:

  1. Not always is main documentation updated at all. Or very late. For example, currently psr-15 documentation is missing in “TYPO3 Explained”. It does have a changelog, though.
  2. People link to changelog rather than main docs (e.g. see links to changelog in SkillsDisplay)
  3. Other sources besides main docs (blogs, Changelog) appear in search results as top pick, even after information was added to main docs.
  4. 2 and 3 have the effect that people find information that is no longer being maintained (blogs and changelog after release) and without context (fragmented documentation)

We do have a main documentation (TYPO3 Explained and others) for a reason. It is regularly updated (well, at least it should be). And the information found there is found in a context (with hopefully an introduction, some cross references etc.)

Now it seems the Changelog is almost becoming the main documentation (for some new features). We should at least take a step back and have a look what is happening.

Important

The extensive documenting in the changelog is a good thing. People are willing to write explanations with code examples etc. In no way do I want to interfere with this! If people are motivated to document (for whatever reason) and write good documentation - do not stand in their way.

Main question

How to handle changelog documentation: Move it to main docs, “copy” it or just leave it in changelog?

  1. MOVE to main docs: Move docs to main docs, link from changelog to main docs
  2. BOTH: Have information in changelog and main docs.
  3. KEEP only in Changelog (do not document in main docs, link to changelog)

Solutions

I think this is pretty clear:

  1. We can’t MOVE the information, because changelog is used heavily (in backend: “View Upgrade Documentation”, extension scanner and for reading through changes for a release on docs.typo3.org: Changelog). Even if we remove the info and add a link, this is not a viable solution.
  2. BOTH is imho the only solution. We don’t want duplicate information. It is bad. But I think, in this case we have no choice. It may sometimes mean, the text from Changelog is just copied. Sometimes new text must be written. It depends. It just means the information in the main docs should be added and the information that is already in changelogs must stay. Even if that means the results are slightly duplicate
  3. KEEP in changelog would mean documenting only in Changelog. I hope we agree this is not acceptable.

Also,

  • Add a link from the Changelog to main docs
  • Do not link to Changelogs from main docs. Transfer the information to main docs.

Migration (todos)

  • things missing in “TYPO3 Explained” should be added.
  • Add links from changelog to main documentation (optional)
  • change existing links to point to main docs (and not changelog)

Related

2

I think I would prefer the option 2 too;
Honestly, I feel that documentation in changelog is too fragmented. if I am searching about how to use the feature “X” I would not want to scan every changelog from since the feature has been introduced (admitting that I know when it was introduced) and all following changelogs in case something has been added or modified. I hope I have explained myself; the ideal thing should be to have full and updated documentation

3

I am absolutely for option 2. And additionally emphasis how important it is to have both sources up to date. So everybody should be willing and able to copy some information only present in the changelog to the docs github repo.

4

I agree we need both. Information from the changelog needs to be integrated with the rest of the documentation. For new features that might initially mean to more or less copy that part - but possibly also with partial rephrasing where necessary. The documentation is something that can be separately worked on and improved.

5

I would like to quote pixelbrackets’ comment from GitHub as well because this sums it up nicely (emphasize in bold by me!):

Thanks for raising this question. My two cents:
A log is a log. It should be considered immutable. The main docs however should be changed & enhanced continually. Therefore both need to exist. And it is absolutely okay to have duplicate content in these documents up to some degree.

The changelog should be concise (you mentioned the extension scanner → as a developer I want to to the able to skim the information) and may contain links to further information.

The main docs should not contain links to the changelog to explain something. This imho encourages cluttered documentation and a “single feature only” documentation style. We however want to describe components and workflows as a whole. With changes! Links should only be set to if the Changelog contains information about the motivation for this change.

Workflow from my perspective:

  • Concise information in changelog
  • Copy and outline information in main docs
  • Add link to main doc in changelog

I think the way to go is pretty clear. I will suggest final result on Slack and then close.

6

Summary and final statement

  • changelog is kept immutable (except for optionally adding links to main docs)
  • main docs are updated to reflect changes (independantly of changelog)
  • Preferably link to main docs, do not link to Changelog (for SEO reasons and for usability, see above)

Next steps:

  • document workflow for updating changes (see PR)