Maintain documentation for old TYPO3 versions before ...?

Archive Documentation
1

Proposal

  • rendered on docs.typo3.org: starting with earliest ELTS (currently 7.6)
  • maintained (meaning they receive updates): starting with earliest LTS. ELTS versions can still get updates but they are not actively maintained.
  • versions that are still available for clone or download: all available versions, we do not remove the branches

I would propose to do the same for the Wiki:

  • a downloadable archive will be provided so people can still have access to the older information. This is similar to cloning the GitHub repositories for docs.typo3.org, checking out the older branches and rendering locally (though it will be easier, the files in the archive can be viewed with a brower, no setup required)
  • things that are only relevant for versions 6.2 and below can be removed

Procedure when an ELTS ends:

  • redirect to next major version, e.g. for 6.2 redirect to 7.6

Current status quo

I already wrote down here what currently seems to be the policy:

Available versions:
We currently have the following policy:

  • Official manuals are available on docs.typo3.org for all ELTS versions and above

Documentation for older versions is still available - if it existed - (in the respective branches on GitHub), see https://docs.typo3.org/Home/WhatsNew.html#finding-documentation-for-older-typo3-versions

This means the older versions (before earliest ELTS) will not get rendered on docs.typo3.org. It will also no longer get maintained. But it is available to clone and render locally.

Disclaimer

I am assuming 6.2 ELTS ends March 31, 2020. Must correct this if I am wrong but the general principles can still apply.

Impact

  • Documentation on docs.typo3.org and on wiki.typo3.org that is only relevant for versions 6.2 and below will be removed (from rendering) and is no longer available online (but is available as git clone or download).

Migration / necessary tasks

  • Wiki: create downloadable archive of Wiki
  • docs.typo3.org: create generic redirect for redirecting to next major version (6.2 → 7.6)
  • docs.typo3.org: remove 6.2 version from rendering (and rename branches 6.2 → 6-2)

Motivation

TYPO3 has a long ELTS period but all good things must end at some point. This proposal aims to remove outdated TYPO3 content where it is available online, turns up in search results and wreaks havoc and confusion. On the other hand, the people that do still maintain older sites (and we all know this is still done though it is strongly discouraged) will still have access to the older documentation, if necessary.

I think this is a good compromise.

2

Sounds like a very legit plan.

3

This decision and also the decision about the Wiki need a decision what can be deleted.

I am not really sure who decides this. This is a prerequisite to be able to do anything. Doing this the way I propose can be a problem for people still using older sites (which are a lot, see statistics by Torben Hansen). To counteract, I proposed the downloable archive of the Wiki.

Today, I submitted this to info at typo3.org as a petition for the General Assembly. Thought the deadline is already past (Apr 2), I am hoping it will be taken into consideration.

I would like to propose to:

  • Decide about deletion process of outdated documentation on wiki.typo3.org and docs.typo3.org

  • I made the suggestion to remove all content that is only relevant for TYPO3 version 6.2 and below (no longer in ELTS) from docs and wiki

  • In addition I suggested to provide a downloadable archive for local viewing of Wiki from current state (I already created this). The older branches from docs.typo3.org are also available via git clone and local rendering.

Motivation: Outdated documentation is one item that is often complained about. This decision will make it easier to delete the outdated information, will reduce the amount of content in general and make the remainder easier to maintain and improve.

On the other hand, many older TYPO3 installations are still online as shown by statistics from Torben Hansen. Making the information available for download will still give people access to this.

More details are in:

4

What are the actual costs of keeping old documentation online (just that, keeping it online)?
To make life easier for upgrades (“What is that removed function/property doing?”) and for maintaining ancient installations (intranets for example) it would be nice to still have them available online.
In order to solve the disadvantages the pages with usual SEO measure could be taken (remove old pages from a sitemap, have no-index, no-follow tags, etc.). Styling in the versions menu could make it clear that it’s an ancient version (or even a separate subdomain/URL). Also exclude them from internal search.

On maintaining documentation: only LTS versions should be maintained by the community. If th GmBH likes to update ELTS documentation they are free to do so.

The wiki should not contain documentation anymore. It could contain things like info for participants of sprints, info on translation teams (if they want to use the wiki), etcetera. For one thing I would like to keep the wiki for practical reasons: the pages about exceptions. A wiki has one nice feature: non-existing pages can be automatically created. In many cases you won’t find any info, but sometimes it’s a real help.

5

First of all, I would like to stress the fact that in wiki and docs there is a lot to do and not enough people doing it. There is a large number of partly outdated and unmaintained content currently. Keep in mind that anything that is proposed here that is extra work is by default unrealistic unless you are willing to do it yourself (or find someone who is willing and can do it).

I am willing to put in a few hours of deleting some outdated pages in the Wiki. But I am not so much willing to do things that prolong the problem and have to be done over and over again and again.

Now, about the concrete suggestions:

What are the actual costs of keeping old documentation online (just that, keeping it online)?

Costs in work hours: That depends if it is still being maintained or just sits there with no changes at all. I recently made several administrative changes to all manuals on docs.typo3.org on all branches (e.g. in Settings.cfg). Not so much fun. It has to be done again and again at some point because of changes in the setup. Some of it can be automated. Costs in Euro - don’t know.

To make life easier for upgrades (“What is that removed function/property doing?”) and for maintaining ancient installations (intranets for example) it would be nice to still have them available online.

I do agree. But it has the drawback of being online, turning up in searchresults. And it makes maintainance more difficult. There are currently more than1000,- pages in the Wiki. Anyone is welcome to try mainaining that. For docs.typo3.org it is a lesser problem, I think. But, for example the “TYPO3 Explained” is currently not rendered for versions below 6.2. (Though branches are still available for below that but not rendered). No one complained about that AFAIK, so far.

So, to still support older versions that are no longer officially supported, we make it more difficult for the maintainers and we make it very difficult for new users.

In order to solve the disadvantages the pages with usual SEO measure could be taken (remove old pages from a sitemap, have no-index, no-follow tags, etc.).

about: no-index, no-follow: AFAIK we currently do not have a mechanism for doing that. That would have to be done in the docs generation and in the wiki generation. How do you maintain for which pages it is done? A good idea, but how much work would that be to implement it?

Remove pages from sitemap: Again, someone would have to do it or rather create a mechanism for automating that and then maintain it.

Styling in the versions menu

Again, a great idea. Would have to be done in the theme (for docs.typo3.org). Again, someone has to do it. (For wiki, there is already the outdated tag, that has been used a lot to tag outdated pages but not all)

Actually I already made several similar proposals as issues already:

Does not necessarily mean they will be implemented.

only LTS versions should be maintained by the community

Agree

The wiki should not contain documentation anymore.

Ok, that seems to contradict what you said above about keeping old documentation online. The Wiki contains a lot of documentation. Most of the really old stuff is in the Wiki and not on docs.typo3.org. Not all of this has an equal representative on docs.typo3.org. So if you propose to remove all documentation from the Wiki, you are proposing to remove the outdated documentation. Do I understand this correctly?

Also, removing documentation from Wiki is not so easy. There are some things that are documented in Wiki, some is still relevant and some is actually quite good. Not everything has a place on docs.typo3.org where it can be easily moved without cluttering up the structure on docs.typo3.org even more. Example: Performance tuning - no real good place to put it (actually a lot of it is outdated too). Also, Fluid, Fluid inline syntax, Composer. Also Extension Development.

So, for starters what I would like to focus on is removing the outdated or duplicate stuff (which has an equivalent on docs.typo3.org and can be redirected). Removing the really outdated stuff (this needs a definition, what is considered “outdated”, e.g. no longer in ELTS). And removing the off-topic stuff that is not TYPO3-specific and where excellent documentation exists elsewhere. That is for example documentation about git, Linux, chmod etc.

To get a better idea of what is there in the Wiki you might want to look at the 2004 category and the candidates for deletion. But you may also want to look at the top 20 accessed pages: https://github.com/TYPO3-Documentation/T3DocTeam/issues/142 and some of the things that are not outdated and do not have an equal equivalent.

P.S. Sorry about the length of this comment. It is a complex issue.

6

I am against the deletion of old versions of the documentation. Sometimes it happens, that you have to work with outdated installations and then it is very helpful to have older versions of an documentation in place.

7

I understand. I have also raised the concern above. I will take this as preliminary decision.

In any case, I am refocusing my efforts to mark outdated content and add links to newer content.

However, there are still some unclarities and things not being done consistently, currently. So I do think it would be good to make some decisions and communicate this and make it easier for new contributors and maintainers to find common general information about how we deal with maintenance of documentation.

First of all, there is a difference between deleting entirely, no longer making available online (but available for download), available online but no longer in search results, deleting from rendering but still available in Wiki history for example and not deleting at all.

In practice, documentation has already been deleted (or removed from online rendering) and scheduled for deletion. It is just not consistent the way it is done and there never really was a real decision made about this as far as I know and this is not being communicated enough (in my opinion).

Let’s look at some examples:

  • Most of the content on the page https://wiki.typo3.org/Cache was deleted in 2017. The content was very outdated, there is newer documentation for the caching framework on docs.typo3.org and the page was originally created in 2008. You still have the old content because you can look at the history in the wiki (but that is pretty hidden and won’t show up in Google). So, is this ok to do so or not? (there are several similar cases)
  • The extension documentation was migrated to the new docs server in 2019. Extension documentation where the author has not updated the webhook etc. will not be rerendered with the new mechanism and will be removed Dec 21, 2020. Example: https://docs.typo3.org/typo3cms/extensions/tt_news/stable/Manual/Index.html However, the content is not lost because it is contained in the extension (just not rendered nicely, but can be rendered locally). Ok or not?
  • As mentioned, the versions on docs.typo3.org before 6.2 are not being rendered, but they are available for download and local rendering, see https://docs.typo3.org/Home/WhatsNew.html#finding-documentation-for-older-typo3-versions I don’t know when this was done or communicated, I wrote the information on that page, mostly just documenting and stating the status quo.

In most of these cases, “deleted” does not necessarily mean deleted and gone forever.

I think deletion (or let’s call it removal from online rendering) should be ok at some point. IF this is communicated early and there are alternatives. It does not have to be right after ELTS ends as I have suggested.

If people are still using 4.5 and below, I think they should already be having a hard time, getting access to relevant documentation on typo3.org in general (apart from the fact that they are using PHP versions that are outdated since 2016 or earlier). And I don’t know if keeping pages in the Wiki of things that were relevant before 2007 (for example) is really helping anyone at all. A lot of the older pages in the Wiki are not tagged for the TYPO3 version. I am having a hard time figuring out, which version they are for (which makes it impossible for me to do anything helpful, except maybe add links to the newer version).

P.S. I am currently deleting pages in the Wiki, but this has mostly been content that was already migrated elsewhere. So far, (almost) entirely moved, redirected and deleted are the Core changelogs, the core release notes (to https://get.typo3.org), the documentation for contributing to the core (moved to the “Contribution Guide”) and some extension documentation (which already exists on docs.typo3.org). See https://wiki.typo3.org/OverviewOfWiki#Number_of_pages Doing only this has already reduced the total number of pages in the Wiki by more than 30% which should make the remainder more easily maintainable.

8

In meantime the wiki.typo3.org instance is gone and most relevant content has been migrated to docs.typo3.org including the exception pages. So this proposal is mainly about the docs.typo3.org.

My point of view: I mainly agree with Jigal and Stefan and would like to keep the documentation for all versions, but handle the versions which are not maintained anymore in the different way that Jigal proposed:

  • render docs of docs.typo3.org for all versions
  • set SEO related meta tags for not actively supported versions
    • remove old pages from a sitemap
    • have no-index
    • no-follow tags
    • …
  • mark pages of not-supported versions
    • with flag and/or
    • with note and
    • with link to current LTS
  • maybe exclude them from internal search (not sure though) or better rate the search results lower
  • LTS versions should be maintained by the TYPO3 community
  • ELTS versions should be maintained by the TYPO3 GmbH
  • big thing: streamline documentation by adding a versioning even for the entry page docs.typo3.org and display the list of all versions there with flags for current-development, current lts, current elts, outdated . Sub-documentations without versioning always show master then.

Maybe it is a good point in time to forge a budget proposal from this decision.