While creating the new Neos Docs Design I came across the comment from @Marc about the deprecation of Array, Collection, …: New design and structure by manuelmeister · Pull Request #95 · neos/Neos.DocsNeosIo · GitHub
I realized that they have been deprecated for a while now and have not been removed yet. I advocated for them to be finally removed. For newcomers it’s quite difficult to see so many (from other languages familiar: Array, RawArray, Collection) named prototypes just to realize they are all deprecated.
Would rather make the deprecation clearly visible. Do you have a suggestion how that should be done to be clear for newcomers.
I don’t have enough insight to justify the removal, but I think I have some ideas how we could improve the api references / docs to be more newcomer friendly.
What is my problem – Journey
My “developer journey”, as I tried to grasp how fusion works:
I scrolled through the docs, but they did not satisfy my urge to understand this new language. I wanted to see how fusion works. So I looked at the api reference.
I saw all possible fusion objects:
Neos.Fusion:Array Neos.Fusion:Join Neos.Fusion:Collection Neos.Fusion:RawCollection Neos.Fusion:Loop Neos.Fusion:Map Neos.Fusion:RawArray Neos.Fusion:DataStructure …Neos.Fusion:Reduce Neos.Fusion:Case Neos.Fusion:Renderer Neos.Fusion:Debug Neos.Fusion:DebugConsole Neos.Fusion:Component Neos.Fusion:Fragment Neos.Fusion:Augmenter Neos.Fusion:Template Neos.Fusion:Value Neos.Fusion:Match Neos.Fusion:Memo Neos.Fusion:Tag Neos.Fusion:Attributes Neos.Fusion:Http.Message Neos.Fusion:Http.ResponseHead Neos.Fusion:ActionUri Neos.Fusion:UriBuilder Neos.Fusion:ResourceUri Neos.Fusion:Link.Action Neos.Fusion:Link.Resource Neos.Fusion:CanRender
First I wanted to see some basic structures: variable definition, if else, array, for.
I assumed that variable definitions are just syntax and not written as those fusion objects.
I didn’t see
else, but I could see something I know.
Neos.Fusion:Casecould be similar. Okay, The example looks quite advanced, but somewhat familiar, I thought to myself. Too advanced for the moment, but I knew I could come back if I needed it. In the description I saw a link to
I clicked on
Neos.Fusion:Arrayand saw that it is deprecated (as a new developer I don’t want to use something that is already deprecated, you want to learn the “correct new way”) and I should use
Neos.Fusion:Joinirritated me, because I just want to define an array I can use later on and not already “join” an array.
So I looked at
Neos.Fusion:Collection, maybe this was the array I wanted. But it itself is also marked deprecated and points me to
Neos.Fusion:Loop…? But I didn’t want to render something yet. So this is also not the thing I was looking for.
At this point, I asked myself for the first time if I really wanted to learn fusion, because I don’t understand how I could be so hard to just create a simple array in fusion
At this stage I don’t want to deal with Eel, because as a newcomer this is an additional new language. I thought I could take a look at Eel after the fusion basics. Once I needed more advanced stuff like copy data from outside the current context/block, like you can with JS or PHP).
I didn’t give up and thought maybe
Neos.Fusion:RawArrayis something. I see this is deprecated as well and that I should use
Neos.Fusion:DataStructure. Finally I see an crucial info:
Evaluate nested definitions as an array (opposed to string for Neos.Fusion:Array)
I was quite relieved that I’ve finally found the answer, but at the same time it just irritated me again that
Neos.Fusion:DataStructurethen links to the deprecated
Neos.Fusion:Arrayagain. (This really should be a link to
I believe, that as an advanced developer starting in a new language, you always try to find structures you know from other languages. Because with Fusion & Eel, you have two languages that both resemble JS and PHP syntax in some way. I know
Reduce from JS, but they are used in a procedural way. With
Collection I associate something predefined. If a newcomer sees those keywords he immediately associates several things with them, and they are most certainly wrong.
If we move these deprecated prototypes into an own collapsed section, describe datastructure as an array with array result and link to the replacing prototype in the deprecation notices, then I think I would improve the newcomer experience.
Maybe, we can solve this with the new docs and a dedicated section for the syntaxes and most important objects of Fusion and Eel. (under an API section like this in my draft restructure docs: Fusion Objects | Neos Dev Docs)
- Group these objects and “hide” the deprecated prototypes
- Explain basically what they do
- Simple examples that also show the “rendered” result for each example. It could make it easier to understand the language/syntax as well.