I propose that we should remove the CSH functionality (including TCA_DESCR) fully in TYPO3 v10.0.
My reasonings:
The concept was really cool back in TYPO3 3.x and 4.0 when the help was displayed inline or via frames, however the main documentation has evolved and the functionality was hidden more and more within 4.x development already to clean up the UI (mainly FormEngine)
We literally haven’t had any maintainer for 10+ years now within Core - thus: we have outdated information, and if nobody will step up this will not change
Currently CSH is very limited and hacky for FormEngine / TCA data and modules, and hard to exchange for project specific information
docs.typo3.org gains more attraction where the actual documentation of fields / functionality as provided by TYPO3 Core could / should be located. This way we do not have to update screenshots or functionality and make new releases for these kind of things
This way, also the base package (tar.gz/zip) gets smaller as we don’t ship (outdated) screenshots for documentation anymore
The technical basis (global array based on XLF language files) is very outdated. The last time there were changes was back in 4.x when I made the overlays “load via AJAX”.
I hardly got feedback on using CSH in the past 4 years - only some minor content updates and questions about “which docs is right? docs.typo3.org or inline CSH?”
I think, inline documentation is very powerful, but it would be even more powerful to have project-specific docs in an installation, where integrators/admins can show context-specific information for every part of TYPO3 - even personalized on a per-user / per-group basis. But the CSH construct seems not the right weapon of choice here.
Impact for v10.0
We’ll deprecate API functions within LanguageService, BackendUtility and ExtensionManagementUtility
We’ll remove all usages of TCA_DESCR and the Backend module for “browsing” the manual within TYPO3
Possible Migrations
We’ve seen some guided tour approaches (currently in TER) during T3UXW a few years back, a way better approach to get newcomers into TYPO3 Backend - lets put more effort in functionality like this
We should include links to docs.typo3.org as much as possible within TYPO3 Core to help integrators, admins and extension authors do things “the right way”
I call for people coming up with good concepts addressing the issues above and create a better UX for both the people writing context-based docs and having them visible. These days, some AJAX / JS based functionality should be built.
I agree, we should usually first come up with new concepts and implement them instead of just removing them, but in this case, I haven’t seen feeling the need for coming up with new ideas.
Just a basic idea for the image issue: Would it be possible to replace the outdated screenshots with a canvas that contains the relevant part of the current screen? Of course this requires a new definition for CSH.
I’m aware this doesn’t solve the overall situation, but perhaps we get some pointers to preserve the functionality.
From the perspective of an extension developer I would say, CSH as it is now can be removed. Never really had it on focus when adding new fields to TCA and users never asked about missing CSH function for fields.
I work pretty often with editors, explain how to work with TYPO3 and so on.
Context sensitive help is always part of that explanations since 2k3!
Everybody (editors) likes that feature!
Yes, parts of the docs are pretty old/outdated. Screenshots: are they really necessary in CSH?
I do not know the exact technical implementation in the core, I just use it in my extensions.
So in the end I am in favor of not just removing another nice feature, but if it needs to be rebuilt, go for it, and remove the old thing as soon as the new thing is in place and working.
From the perspective of a user (editor or even integrator), I’d say that it should be kept. If I don’t remember how something works, it is easier to click on an help icon that brings me to the correct topic, instead of browsing the online documentation.
[addendum]
My opinion is always: if you remove information, the same information (or better) should be available somewhere else.
[addendum 2]
Should it be possible to have the same source for both the online docs and the CSH? so you don’t have to mantain two separate things?
I agree with Benni, the current experience of help clicking in the field title is not so useful, so in my opinion we can remove it.
A better solution’d be link a form to the specific page in TYPO3 docs.
I totally agree to remove CSH. Because from a user point of view, if we look honestly at the current situation, either the texts are not translated or they are translated but not up to date. I would much prefer spending time to improve the interface so that it is easy to understand without context sensitive help rather than translating additional texts that explain how it works.
Also, when I needed to translate some of these texts, I found it complicated to understand the original meaning inside an xlf file that was completely taken out of the interface context (which is annoying for “contextual” help texts!). It is also not easy during this task to take the time to make up-to-date screenshots in the right language… I would therefore say that the very principle of contextual help asking translators to work without context is rather badly designed. A good contextual help can only work with quality texts and screenshot, otherwise, it doesn’t help at all.
This feature is highly underrated. It’s quite powerful and possible to replace and extend for custom installations. Still I don’t know many people making use of that. Right now I would go for the deletion, even if I hope this would improve user experience. But therefore agencies and freelancers should now about it, and use it.
Hopefully we will come up with something better in the future.
I’d agree that the current state is not very helpful and a complete rewrite would be necessary.
I’d agree with a removal in the sense that the replacement need purely manual steps for migration and have no automatic migration path.
The basic proposal towards docs.typo3.org is fine, but could be summed up as “just RTFM”. This is an approach I’d deem plausible towards developers, integrators, administrators, but not towards editors.
The proposed guided tours replace documentation on first access, but would not cover the mighty hidden features already mentioned above, which e.g. could help in edge cases how to fill out a field correctly based on the semantics of the record.
Thus, a UX concept of not leaving the current context to get help should stay in place, because it might be needed for editors. An extension could override a field and thus override the relevant docs: e.g. a sitepackage explaining what the values Layout 1 and Layout 2 in context of this sitepackage mean. Even if we were to rename the values or add new values, the docs.typo3.org would neither have information about it, nor would it host the sitepackages documentation.
As a user I like help information to be presented right at the spot and not somewehere else. Of course a complete explanation of a broader scope is fine on docs.typo3.org. But a short reminder on what a UI element does is good thing to have within an application (web or not).
I agree with Rachel: Improve the user interface as much as possible (instead of documenting something that would not need the extra tip if it were easier to use and understand.) IMO, that should be the top priority.
But, I do also think people would like to have the information available in the BE or at least not have to search for it elsewhere. I do see the functionality as useful and have used it. But I understand the points Benni raised and have to agree.
Better integration BE + docs.typo3.org might be an interesting new project! It would be nice to jump directly to the docs from the backend.
Please, drop current CSH implementation. I’ve spent time on the Dutch translation of labels (core + extensions) the last months and the CSH is largely untranslated (even for outdated versions).
I haven’t heard much from editors who actually use the current CSH.
The idea of finding a mechanism that links features in the backend to online docs would be awesome. Perhaps there could even a way that we can measure attempts to get help for things that are not yet in the documentation. That could trigger people to write docs about those areas. (we already discussed the problem of empty wiki pages for many exception codes during one of the devdays)
For now dropping CSH without replacement would be a good idea to me.
As a summary from what I understand from all your feedback - which I HEAVILY respect that you spoke up:
We all agree that we need a “next generation” of CSH. a better form of “in-system-documentation” is necessary, integrating this with external documentation would be great.
There is still some (I’d say 20%) of the people discussing that use this functionality - and strive for keeping it as long as there is no replacement.
For TYPO3 v10, there is no better approach available / planned / sketched or outlined currently, so I suggest to keep it around for the time being.
I also don’t have a good approach as a replacement at hand, but if there is an incentive to push this forward, I’m happy to support / work on it as well, but the integration / replacement will most likely happen after TYPO3 v10 LTS.
I’ll keep this topic closed but we have a good overview as a reference kept here on this platform.
Thanks for all your responses, this is exactly how we should discuss and share our opinions.