plone
Broken documentation links
IMO it is very important to make all those broken links work; some are on our own pages (and could be fixed in the text, for a start), but others are elsewhere. All of them should be handled by useful redirections. (An example for a not only entirely useless but even harmful redirection is https://plone.org/products to https://plone.org/download which not really helps e.g. with https://plone.org/products/archetypes/documentation/old/ArchetypesDeveloperGuide/).
Some broken links:
- https://docs.plone.org/4/products/example.archetype/, found on https://docs.plone.org/4/en/old-reference-manuals/archetypes/a_simple_at_product/introduction.html (first posted here)
- https://docs.plone.org/4/en/tutorial/customization-for-developers, found on https://docs.plone.org/4/en/old-reference-manuals/archetypes/a_simple_at_product/view_template.html (the next post)
I'd really like to have those links work again, which might involve recreation of sites and paths which have been put aside when docs.plone.org was established.
Broken: http://plone.org/documentation/kb/portal-transforms, found in
- https://docs.plone.org/4/en/external/plone.app.dexterity/docs/advanced/rich-text-markup-transformations.html#alternative-transformations and
- https://docs.plone.org/external/plone.app.dexterity/docs/advanced/rich-text-markup-transformations.html#alternative-transformations
Broken: https://docs.plone.org/external/plone.app.testing/docs/source/index (Plone testing tutorial), found in
- https://docs.plone.org/4/en/external/plone.app.dexterity/docs/testing/unit-tests.html and
- https://docs.plone.org/external/plone.app.dexterity/docs/testing/unit-tests.html
Edit:
I just found the versions https://docs.plone.org/4/en/external/plone.app.testing/docs/source/index.html and https://docs.plone.org/external/plone.app.testing/docs/source/index.html to work; obviously those links rely on a server feature which appended .html automatically, or the ids of the pages have indeed changed.
Broken: http://plone.org/documentation/tutorial/testing (even older address of the Plone testing tutorial), found on https://www.plone-entwicklerhandbuch.de/anhang/referenz/testen/einfuehrung-in-unit-tests
Broken: http://developer.plone.org/searching_and_indexing/query.html (don't remember where I got this); redirects to the wrong destination https://docs.plone.org/searching_and_indexing/query.html (should be https://docs.plone.org/4/en/develop/plone/searching_and_indexing/query.html)
Broken: http://plone.org/documentation/manual/plone-4-user-manual/using-tinymce-as-visual-editor/introduction; wrongly redirected to the root of https://docs.plone.org/. Should be https://docs.plone.org/4/en/working-with-content/using-tinymce-as-visual-editor/index.html.
@newbazz you don't need to comment like that. The status of this issue (Open) means it has not been resolved, and there is no Assignee so no one has taken it on. To proceed, assign yourself (this let's others know you have taken it on), then submit a pull request (this let's others know you have done work that is ready for review).
(as long as I don't know a better place, I'll continue to add broken documentation links here ...) Broken: https://plone.org/documentation/manual/developer-manual/generic-setup/reference/properties-ref, found on https://docs.plone.org/4/en/develop/addons/components/genericsetup.html#propertiestool-xml
My idea would be to create a solution to make Plone use a relational database to manage redirections and suggestions; see issue 918.
Broken: https://plone.org/support/providers, found on https://docs.plone.org/intro/index.html as "over 300 solution providers". Broken: https://plone.org/support/hosting-providers, found on https://docs.plone.org/intro/index.html as "plone.org".
@tobiasherp @mredigonda sorry that you are finding all these broken links, and many thanks for providing the correct places where they should actually point to. It would be awesome if you could create a pull request to make the actual changes.
We are about to release a new major version of Plone (5.1) and now is the perfect time to fix all these broken links, so that newcomers and oldtimers alike find it nice and unobtrusive to browse our docs.
TIA!
@gforcada : There are several problems with the "pull request" approach:
- It requires everyone who likes to contribute to create a fork of plone.documentation, which is an unnecessary hurdle
- What will you suggest for pulling if you don't know the correct new location?
- Updates of documentation links require both a new release of plone.documentation and an instance restart, right?
IMO, a database solution would be much better which would handle redirections from the old locations (which are still found in the docs) to the new locations; every now and then, the changes in this database could be used to fix those links. Thus, please tell me what you think about issue 918.
@mredigonda
These are fixed now on GitHub by https://github.com/plone/documentation/commit/517a2e348ca254dcd765dcac4874b0c11893b8f7
@tobiasherp
Updates of documentation links require both a new release of plone.documentation and an instance restart, right?
Yes and no, a new release is needed yes, we are working on getting them out faster and no there is no instance restart needed :)
You fixed the last broken one... but not the links he said above and in the beginning of the issue @svx
@tobiasherp @stevepiercy @gforcada I'll suggest adding a section where users can report broken links with some small authentication like github o-auth or any first party login facility... This would help us in maintaining links as I believe there might be more broken link now or in future that might go unnoticed under our eyes but is noticed by users... As reporting to Github or in our community involves several steps that sometime doesn't feel good for a simple report... More counter opinions are appreciated.....
@rohnsha0 please see how we solved this dilemma in the Plone 6 docs:
- https://6.dev-docs.plone.org/contributing/setup-build.html#linkcheck
We now have automatic deployments for Plone 6 docs. Earlier versions of Plone docs require manual intervention by a few privileged maintainers.
For versions of Plone that are no longer supported (pre-5.2), it is not worth anyone's time to fix broken links. I don't know if it is even possible to build Plone 4 docs anymore. Let them rot.
For both version 5.2 and 6, the way to fix a broken link is to submit a PR to fix it. It does not get any simpler than that. We do not want redirects at all.
In fact, in the Plone 6 docs, we routinely update links that redirect. make linkcheckbroken detects redirects, unauthorized, throttles, and any other directly unreachable link.