Where do you expect your TYPO3 documentation?

Documentation
#1

Current situation

Currently the WIP documentation for the newest Version can be found at “master” i.e.
https://docs.typo3.org/m/typo3/reference-coreapi/master/en-us/

The latest stable versions documentation can be found at “10.4” i.e.
https://docs.typo3.org/m/typo3/reference-coreapi/10.4/en-us/

And the old stable version at “9.5” i.e. https://docs.typo3.org/m/typo3/reference-coreapi/9.5/en-us/

The documentation for the eLTS versions can be found at links like “7.6” i.e. https://docs.typo3.org/m/typo3/reference-coreapi/7.6/en-us/

We provide no documentation for past minor versions. So one 10.4 got released we maintain not documentation for 10.3.

SEO problems

This leads to the master version (even if its still mostly WIP and only in interest for rare cases) and versions often linked to be most prominent on Google. Often all you can find is documentation for versions 7.6 and master = 11. Once we start working on the documentation for a new version the current stable version gets renamed.

Suggested solutions

  1. Always use the main version
    v11 would be the current WIP version
    v10 the current stable
    v9 the old stable
    v8 the elts
    etc

downside links to v10 always point to v10 and do not promote v11 once it is stable

  1. Use descriptive links
    develop is version 11
    stable is version 10
    older versions are v9, v8 and so on

downside on new releases links pointing previously at 10 now point at 11

  1. The best of both worlds?
    using both notions with redirects, symlinks and or canonical urls?

  2. keep everything as it was

Additionally I would suggest to have a link at the top of each document to the current stable version when you are using another version.

1 Like
#3

I consider it a SEO disaster if different documents are indexed with the same URL (over time).
for SEO all documents should be available with a unique, canonical URL which only includes the Major version.
there might be further paths which vary in redirects to different versions over time: ‘master’, ‘stable’, ‘latest’ so that links continue to work. but as the target vary, those URLs should not be promoted and spread (like search engines do)

a further SEO aspect:
to avoid duplicate content it would be good if an unchanged document keeps the canonical URL of the first version, but that probably is difficult to realize.

A more complete document would be one common document for all versions, where every feature is listed and has the information in which TYPO3 version it exists. Or as an interactive document: where you can filter the list of pages and feature to a specific version to see only the documentation of this version.

#4

Lina, can you be a bit more clear about what exactly you mean? It is not clear to me what exactly is being proposed. Do you mean in the URL, meaning we would not use /master/, but use /11/ or /11.0/ instead? Would the “master” URL not exist at all, would it redirect …? How will the branches be named? What is displayed in the version selector? Meaning will you also rename the branches or will you just redirect, e.g. “develop” to “11”, “stable” to “10”.

e.g. https://docs.typo3.org/m/typo3/reference-tca/10.4/en-us/

https://docs.typo3.org/m/typo3/reference-tca/develop/en-us/

I think before we start discussing it is important to know what exactly is being proposed.

It would also be good to know how this will impact the maintainance effort and how much effort it would be to change this.

Also, a number of suggestions have already been made in this area (see open issues and decisions). I believe I already made the suggestion to name each branch with explicit version (using only master - not master.minor as currently used, e.g. 11 instead of 11.0) and have a redirect from master to the version.

I agree that the word “master” is non intuitive for non-developers. It should however be intuitive for developers (although GitHub is already changing the default due to avoidance of terms “master”, “slave” etc.) - so it is really a problem since most of the documentation is for a technical audience. The current process corresponds to the core development repository and branching.

#5

I would prefer URLs with version numbers. That way the assignment is unambiguous. I would only take the main version number, as the sub-version may not be so well known. Similarly, I would use the language without the regional variation:

Google would have to learn which documents are more up-to-date as they do with newspaper articles. As far as I know, however, this cannot be influenced via the URL.

And if “master” remains, please rename it to “main” or something similar.

1 Like
#6

Maybe we can have a mixed solution.

The latest LTS version should point to an url, which does not change and will be replaced with next LTS version, once it is released:
https://docs.typo3.org/m/typo3/reference-tca

Any release version should have it’s own version scheme:
https://docs.typo3.org/m/typo3/reference-tca/10.4/

A version in development could point to
https://docs.typo3.org/m/typo3/reference-tca/develop/

The language tag should only be visible for translations. Standard is english.

#7

I would also consider using URL with version number only. Maybe with some symbolink redirect for named versions (latest, stable, etc.).

I would also consider adding a banner reminding if it is the latest version or older. With a tip to use the version selector.

Thus URL are persistent and the reader is less confused.

#8

I guess that IMHO the URLs are not the problems solution.
For URLs: what ever you decide, make it understandable for humans.

I think it is a kind a UX topic. My suggestions:

  • Make the version chooser more prominent, so that where ever you land, you can easily go to your version.
  • Make a hint on the top of every document, saying “This is a outdated version, here you can find the current one.” (link to current version)
  • A nother point could be, add the version number to the documents title and H1. This will help people, who use the version number on a search term. In this case, Google, Bing and so on could match that to the term.

In the end, you don’t know with what version the user is working currently. So maybe the old docs are important for him.
But if every document have a link to the current version, this will help to rank the current version better on search engines. Maybe those links can be generated automatically.

#9

the problem which occured: google links to the master branch, which is the currently worked on branch (at the moment it is 11, which is used only by few people).
from the google search results.you can only imagine the version from the url.

If you need to choose the version after google brought you to master you need at least one further click… (bad UX)

the version (and the version selector) may be presented more prominent (in a SEO way). so you can search selective giving google the version number and your question.

#10

I would expect to see the version number more prominent, so no matter where you land, you can go easily to your version. I would avoid mixing version numbers with master/development/latest/old words that are not really interesting for me, if I work with version 9.5 that’s my version, i’m not interested in the latest or the new WiP version, because I’m searching documentation for the version i’m looking for.

I would expect to see the version number in the url very close to the word “typo3”
the current Url https://docs.typo3.org/m/typo3/reference-coreapi/9.5/en-us/ tells me this is the version 9.5 of the reference-corapi section (and not of TYPO3).

while something like
docs.typo3.org/typo3/9.5/reference-coreapi/en-us/
tells me it’s the TYPO3 version 9.5 documentation, section reference-coreapi/

or

docs.typo3 .org/typo3-9.5/reference-coreapi/en-us/

or

docs.typo3 .org/10.4/reference-coreapi/en-us/

this will be easier to read and will also help SEO (maybe).

Hope my 2 cents brings something to the discussion

#11

Please let me explain the current setup. I’m not going to provide a solution or opinion in that post.

The new URL structure follows this pattern:

<domain>/<type of package>/<vendor>/<package name>/<version>/<locale>

Domain is always docs.typo3.org.

type of package can be:

  • m for manual, official TYPO3 manuals hosted on GitHub
  • c for TYPO3 system extension (core package) like dashboard
  • p for any 3rd party package, e.g. extensions
  • other for other related things like fluid or surf products.

vendor and package name are fetched from composer.json.

version has to be a major and minor. This follows https://semver.org/ where major contains breaking changes and minor contains new compatible features. While the third patch version only contains compatible bugfixes.
There are two exceptions: master (main) and documentation-draft.

locale contains the actual locale, e.g. en-US or fr-FR.

You can find this information at: https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingDocForExtension/Migrate.html#url-structure

Keep in mind that we are not talking exclusively about official TYPO3 manuals, guides and tutorials, but about a whole platform and infrastructure which allows the whole community to host their own documentation. Therefore those generic rules were defined to support all known requests. Also the URLs are human readable, easy to understand and adjustable. In case a user lands on version x.y of an package, e.g. https://docs.typo3.org/p/georgringer/news/8.3/en-us/ he can change the version to https://docs.typo3.org/p/georgringer/news/7.3/en-us/ by changing the URL, beside the version selector.

Also people can “know” urls, e.g. by looking at composer.json of an installed extension. Software can build urls and test if the documentation for a specific version of a package exists.

master reflects the actual master branch. Where main is accepted as an alias under the hood. That follows industry standard and best practices in terms of VCS usage.

I hope this explains at least the current structure and provides some more insights.

#12

Now let me add my personal thoughts.

I hear some people complain: I don’t know which URL I should use as a link in my blog post or manual. I don’t get that point. Every blog post, every manual, every extension is build for a specific TYPO3 version. That’s also part of composer.json or ext_emconf.php in case of extensions. Blog posts should define which versions they cover. Therefore, it is clear that one of the supported versions should be used, to keep users in context. One should never link to master, except if that’s exactly what is necessary, linking to master.

Regarding SEO: That’s not my topic and I have nearly zero knowledge regarding SEO. But it looks like we are not even discussing SEO. At least my understanding of SEO is search engine optimization. Actually the pages are indexed and can be found. What we are talking about is search engine user experience. It looks we think people are lead to wrong results. Is that even proven? Do we know we have an actual issue in that area? Do we have asked whether people have issues, and which issues they have? I’ve read most people complain about version number not to be visible and version switcher is still too hidden. I would not say that this is only related to search engines, but also to bookmarks and browser history.

Coming from a technical background: I would first define the real issue, and proof this issue exists. Afterwards define the expected result, taking all requirements into account. Then find a solution to meet these requirements.

#13

Currently the WIP documentation for the newest Version can be found at “master” i.e.
https://docs.typo3.org/m/typo3/reference-coreapi/master/en-us/

Hey. As a general remark on this statement: Please do not treat ‘master’ as ‘WIP’!

The master branches of the official core docs relate to the master branch of the core repository. Those are not WIP in the sense that they can be randomly broken and eventually fixed later: Core version 11.0.0 has been tagged right from master branch and it is a stable version (it is just not an LTS). The docs team should treat the master branches of the core related repositories the same way: If you’re doing WIP stuff like a bigger refactoring including broken things in-between changes, then please do that in some other branch (eg. the ‘documentation-draft’ branch, which is exactly for this purpose), and merge that branch to master when it’s ready.

There are many extension / other repositories that do this in a similar way: A release is tagged-off from the master branch, and older / legacy versions are tagged off from legacy branches.