search

FluidTYPO3 / vhs

TYPO3 extension VHS: Fluid ViewHelpers
https://fluidtypo3.org
Other
189 stars 228 forks source link

Sad about new Documentation #1693

Closed fischhase closed 1 year ago

fischhase commented 3 years ago

Hallo dear Developers, thank you for your great work. Your Extension is one of my favourites. But one thing I am really sad about: Your Documentation has changed. Now it is just a automatical generated List of commands and parameters. Once there was a documentation, much better in design and function. It had working examples, inline formats and maybe also comments (I don't remeber exactly).

https://viewhelpers.fluidtypo3.org/fluidtypo3/vhs/5.0.1/

Maybe it was too much work to keep it up to date, but know it really doesn't help so much.

Thanks anyway Martin

MarkusBausK commented 3 years ago

I can confirm this... The old docs were a really important daily tool for us :-(

sebastianhomeier commented 3 years ago

I second that. Also, documentation for 6.x versions is missing completely.

grimmcreative commented 3 years ago

Would be so great if we can get back the old Version. I would sign up voluntarily also to keep it up2date.

me84 commented 3 years ago

Thats true. I'm absolutely missing the old Docs. Why cant we get both?

dkern commented 2 years ago

I would not even call the new "thing" a "documentation". It's really garbage, sorry. 😞 I know, it's easy to criticise open-source software, but there already was a better solution and they switch to a worse one.

ingeniumdesign commented 2 years ago

yes we need the Code Examples back 👍

NamelessCoder commented 1 year ago

In the future, ViewHelper references are updated automatically and can be found on https://docs.typo3.org/p/fluidtypo3/vhs/6.1/en-us/ (select your version in the left menu). A fully automated solution has been implemented - after acknowledging that even the reduced manual workload required by the more recent iteration of the documentation still caused the documentation to quickly become outdated.

So: every ViewHelper in VHS has had its usage examples updated to render correctly in this new location. From now on, this is updated automatically with every single release that happens.

For the ones that are sad about the code examples: I'm sorry that you miss this, but it is unlikely to come back. The old documentation renderer created these code examples by very loosely guessing what a proper value for a given argument would be and then rendering the example with such assumed/guessed arguments. This was very far from perfect and in too many cases caused the documentation to contain examples that would never work if you copy-pasted them.

In addition, the ViewHelper documentation is now rendered by the official ViewHelper documentation generator and as such, follows the same standards and produces the same output as official TYPO3 core ViewHelper documentation. It is therefore not possible to restore this guessed approximation without also activating it for TYPO3 core ViewHelpers and due to the misleading nature of guessed argument values, this would never be accepted there.

The right way to get these examples would be to update the ViewHelper documentation within the PHPdoc class comment of each ViewHelper class (and you are absolutely more than welcome to help with this!) - but the automated, guessed approximation is unlikely to ever return.

So I'm sorry if you still miss these examples. I hope the new documentation rendering is at least more useful to you. And I hope that those of you who really liked the code examples will help build proper code examples by contributing changes to VHS to add these examples for the ViewHelpers that currently don't have them!