it seems to me there is little official online documentation for Extbase that is up to date and reliable. This overview page hits the same line and points to a book by Michael Schams.
From what I heard, the reason for that is just a lack of manpower as in any other OSS project. So please let me assure you, this is not about blame: I appreciate what’s there and I don’t blame anybody for what’s not there, especially because I didn’t have the time for any sigificant contributions in that area myself.
Of course I could now just go and buy the book and be fine with it. I really appreciate that such books exist, as they do have their USPs, for example a more “tutorial-like” approach and in-depth explanations (actually, I’ve bought the first two extbase books by Patrick Lobacher and Michael Schams, and would surely also buy the third one
At the same time, we all know that having a free and up-to-date, reliable source of documentation is vital to any open source project as it is one of the main factors to attract new people to the community and keep them happy. So this is simply something people sort of expect.
So, as the manpower situation seems to be on the same level for some time now, the first idea that came to my mind was: “Why don’t we just pay Michael Schams or others with money from the association to do this work for the community, based on their book?”
Maintenance of the documentation would probably also be easier once we have a “fresh” start.
What do you think about this?
Pro: Probably gets the job done fast and with good quality
Con: Offering money as extrinsic motivation for community work may lower intrinsic motivation; where does this end?
What exactly are you missing in the documentation? Some examples would be really helpful. I personally almost never go to the extbase documentation. For the documentation of fluid i go right into the viewhelpers. The only thing I sometimes need to look up is validation to look up the right syntax.
TBH, actually I noticed that it’s better than I had in mind - after taking a closer look, I found many of the things that I thought were missing So an entire rewrite should not be nescessary, maybe just an update, clarifications and wording / structure improvements might be enough. Here are some topics that I would like to improve:
Request/Response cycle: when does it start, when does it end (explain dispatcher), especially in conjunction with forward() and redirect()
Validation: Explain a little more in-depth when and under what circumstances validation happens (people often wonder why validators aren’t called although they made controller annotations in conjunction with using forward() )
Validation: Best practice on how to validate models which were not filled using the property mapper in context of a controller argument. For example, models filled in an action using data from an external API or so.
Validation: Example on how to validate properties in nested objects, depending on parent or child objects and bind results to properties
Validation Results: explain that they can (but do not have to be) bound to properties
mention that validators do not “return” false or true but add errors instead
Validation Results: Explain that validation results have nothing to do with flash messages
Validation Results: Explain where they come from (originalRequest, …), in context of errorAction
Explain and give examples for multi-step-validation
Property Mapper: best practice where/how to configure the property mapper, including an explanation of options (allowCreation vs. allowModification, allowProperties, allowAll, allowExcept, etc.). Use case: data from external forms
Explain hidden fields placed in forms using f:form
How to write custom typeConverters and when do they make sense
When do I have to persist manually, when does extbase do that for me, and why?
btw. back in ?, Michael Schams already handed in a budget application to write an Extbase / Fluid book for docs.typo3.org. This was highly voted, accepted and then merged in with the TYPO3 documentation budget. (Unfortunately, I can no longer find a link or more information about this, maybe someone can help out?)
As @speters pointed out quite rightly, I tried this approach before and submitted a budget application in 2017 for an official Extbase documentation:
“Produce a proper and up-to-date documentation about Extbase in understandable, high quality English language, published under a non-commercial Creative Commons license at docs.typo3.org. […]”
The application was rejected, but the budget requested by the Documentation Team increased and a comment added “The EAB sees this initiative as a catalyst for other documentation initiatives e.g. the Official Extbase Documentation” (see budget 2018).
Unfortunately. I did not come to an agreement with the Documentation Team for several reasons (no blame game here). As a consequence, I wrote and published the 3rd edition of the TYPO3 Extbase Book which quickly became the de facto standard and is still thriving today
I am not against the idea of improving the Extbase documentation (or any other TYPO3 documentation) and I’d be open for discussions. However, with my past experience, I have some doubts that this would unfold differently this time.
Thank you all for the insights. I still think that paying someone on a constant basis to improve documentation could be worth a thought, however I see the difficulties which come with that.
For the time being, I’ve created a couple of issues in github for those things from my post I’d still like to see in the documentation and if I find time, I might get some of them done myself
So an entire rewrite should not be nescessary, maybe just an update, clarifications and wording / structure improvements might be enough. Here are some topics that I would like to improve: