Changed documentation locations

Documentation
1

There are many dead hyperlinks around, linking Plone documentation pages which have gone or (hopefully) moved a long time ago. This is a severe problem, IMO, and we should do whatever we can to

  • establish HTTP redirections, whereever possible, and/or
  • collect the information about old and new locations in one place.

I just found two more dead links here (both Backup Plone and Backup and recover Data.fs in linux are dead), but there are dead hyperlinks in https://docs.plone.org as well.

We can't correct all of those outdated links out there ourselves, but we can make those https://plone.org/documentation urls work, right? They should redirect to the current location (HTTP status 301) or perhaps to overview pages which list current locations (if more than one).

2 Likes
2

Contributions of documentation pull requests are always welcome! Even if you fix just one old/broken link and update it with a current location it helps. Even better: if the current location is not in our documentation, move the information into our documentation...

3

My problem is: I'm not the one who knows about the details of those changes. I simply hope that the guys who did this know what they have done ...

4

Thanks @tobiasherp - my suggestion was for everyone, not pointed (only) at you :slight_smile: - you've already helped by pointing out the issue.

5

Maybe this is a way to start:

(not tested, 'just' out of my head)

rewrite ^/documentation/(.*)$ https://docs.plone.org/$1 permanent;

This would also solve the issues which we still have with old kb articles.

  • Look through the content of https://plone.org and remove old content, like old news articles which are telling about https://plone.org/documentation and so on.
    During the site migration lots of old content got migrated which is not accurate anymore.
  1. Update GA, to let SEO and thus also Google know.
1 Like
6

What should be updated in Google Analytics?

7

Good idea - at the very least I can add the basic plone.org/documentation -> docs.plone.org

8

Will push this live soon.

9

Sorry I mean GA-Webmaster tools.
If you use GA-Webmaster tools, you can update the index, by doing that you can improve the 'score' in Google and with that old articles are gone from search engine index which means its better and less confusing for user.
Otherwise plone.org will still tell search bots about incorrect content :).

10

It's been deployed, so anything going to plone.org/documentation is redirected to docs.plone.org

11

I just reloaded https://plone.org/documentation/how-to/backup-plone to see the effect and noticed that it simply redirects to https://docs.plone.org/. I'm not sure this is very helpful; I would be happier if it would lead to a page telling about backing up Plone.

Perhaps it is possible in many cases to apply a simple transformation and preserve parts of the path information, like @svx suggested.
I know this is a per-page task, but IMO it must be done.

My suggestion would be to do the redirections for known old-and-new pairs as systematically as possible, and as a last resort use an error page telling "sorry, this page has moved, and we don't have a redirection yet. You may contribute here ..."

12

As this swallows any further given path information - e.g., the /how-to/backup-plone part of https://plone.org/documentation/how-to/backup-plone is dropped - I doubt this is an improvement; see my post earlier today.

13

Your help would be appreciated... let me know what you think these two lines should be

14

I'm sorry, I don't know much about the possibilities here. I know about Apache redirections; there, it would be possible to redirect e.g. ^/documentation(/.*)?$ to https://new.domain/new/root$1 and thus preserve the information from the optional bracket in a very generic way. Perhaps the error page on the target system new.domain can make use of a request variable (e.g. old_location) and tell about the (failed, in this case) redirection.

15

For the records, and hoping for a better solution:
http://plone.org/documentation/faq/plone-read-only-mode (found on https://bugs.launchpad.net/collective.buildout/+bug/712204) now redirects to the documentation root for Plone 5.

There seems to be a copy on http://www.tuxdroid-community.org/archives/oldsite/tuxisalive.com_httrack_copy/plone.org/documentation/faq/plone-read-only-mode.html; thus, there is a chance to find the contents of http://plone.org/PATH in http://www.tuxdroid-community.org/archives/oldsite/tuxisalive.com_httrack_copy/plone.org/PATH. For a redirection, we should have a destination which is controlled by the Plone community, of course.

16

The generic redirection is there because there is no longer a documentation folder in plone.org

Anyone can submit PRs for new redirections at: https://github.com/plone/ansible-playbook/blob/plone-org/local-configure.yml#L164

1 Like
17

Alternatively, someone (you?) could submit a PR for the docs that includes the material you found. https://docs.plone.org/about/contributing.html

18

We could change the redirection include the rest of the path, so that plone.org/documention/backup would go to docs.plone.org/backup regardless if we already have this content or just not under the same url. Then we could just handle all the redirecting in the docs repo. @svx could we add redirects inside the docs?

But maybe it's enough to point the user to a page where we say what to do, like @tkimnguyen suggested making PRs for the Ansible playbook. So adding a page in the docs and pointing to it.

But the broken links from the docs to old plone.org we should fix soon.
@svx don't we have a link checker in the docs already, or is it only for internal links?

19

@MrTango what do you mean with:

???

As for checking links of docs.plone.org, we do run a linkcheck over the whole docs, currently the check is 'only' reporting and not failing, that has simply to do with the reason that we still have way too many.

Here for example is the ticket regarding plone.org -> Fix links to plone.org · Issue #618 · plone/documentation · GitHub

The situation is far from perfect, we know that.

At least for plone.org this has to do with the reason that for various reasons the new plone.org was released in kind of a hurry and ppl forgot or do not had the resources to do that more carefully. One of the many perks in a small community where a small amount of ppl doing too much at the same time, but that is a different story. :slight_smile:

So yeah, I guess we have to deal with the fact that we will not get it perfect, taken the amount of resources [people and time] which is sad, true but that is how it is right know ....

Usually we try to fix a couple of broken links, which every new release of the docs, but like I said we have a lot of them and thus it will take time. It would be helpful already if ppl stand up and help with that.

I do not understand the other part of the posting, everyone can run a scraper over a website and host that copy, there is not much we can fix there.

IMHO for now what we have is not really cool, but still good enough, you end up on the main site of docs.plone.org, that is better than ending up on old.plone.org.

Mapping all the old content to the right places of docs.plone.org also brings some disadvantages, for example we started to improve the use experience by moving stuff to different locations.

What we maybe could do is a new template on docs.plone.org and configure the webserver in a way that, lets say if your request is coming from a plone.org redirect you get the new template telling you that docs.plone.org is the 'new place' bla bla bla ....

:slight_smile:

20

Yes we need just some more helping hands here, so lets improving the situation by guiding people and give them an easy way to help.

Lets add a page to the docs, with the needed information like the place where to add redirects, as @tkimnguyen mentioned above. On this page we can explane how they might find the missing docs in docs.plone.org and that they should help by adding redirects to plone.org to the new content.

In case we move things around in the docs, do we have a solution there to redirect inside the docs, like Plone does by default?
We need something or we will produce more dead links from outside in time.
So we need at least a workflow for that. @svx do have any idea how we should handle this?

1 Like