Make the fusion api references more newcomer friendly

Community Newcomer's Corner
1

Context

While creating the new Neos Docs Design I came across the comment from @Marc about the deprecation of Array, Collection, …: https://github.com/neos/Neos.DocsNeosIo/pull/95#discussion_r1029196499

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.

@mficzel replied

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.

Proposal

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 if or else, but I could see something I know. Neos.Fusion:Case could 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 Neos.Fusion:Array.

  • I clicked on Neos.Fusion:Array and 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:Join.

  • The name Neos.Fusion:Join irritated 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

    :warning:
    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:RawArray is 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:DataStructure then links to the deprecated Neos.Fusion:Array again. (This really should be a link to Neos.Fusion:Loop)

Conclusion

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 Join, Loop, Map & Reduce from JS, but they are used in a procedural way. With Array & Collection I associate something predefined. If a newcomer sees those keywords he immediately associates several things with them, and they are most certainly wrong.

Solution

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.

TLDR

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.
7 Likes
2

Thank you for your write up. Such things really help to make neos better! <3
And i fully agree with your points.
I think the current consent was that keeping those few prototypes wouldnt be technically a problem so they were simply not removed… Thats definitely the goal i think with 9.0.
But we can already just totally kick them out of the docs, or just list them as to be removed without with their replacement and no further details.

Im not sure whether we want them directly inside of the neos docs or keep them separate in read the docs via rst. Currently the are relatively close to the code and versioned. I even had the idea to write the docs inside fusion and generate the rst dynamically. TASK: Split basic fusion prototype files and define defaults by Sebobo · Pull Request #3915 · neos/neos-development-collection · GitHub

1 Like
3

We could move the docs of deprecated prototypes into a seprate section with a clear warning to seperate them from the stuff we actually encourage to use.

Also Neos 9.0 may be a good time to finally get rid of:
-Neos.Fusion:Array
-Neos.Fusion:RawArray
-Neos.Fusion:Collection
-Neos.Fusion:RawCollection

2 Likes
4

Just here to say THANK YOU!
This is so much helpful context and actionable feedback. I can’t even express how welcome it is when people stumbling through new tech do this and write-up their experience as feedback for the developer community.

It is invaluable and that’s not an exaggeration.

And then you’re not stopping there but also doing the PR to improve the docs on this actionable feedback yourself :clap: :blue_heart:

5 Likes
5

I like the structured presentation of the prototypes in your draft, especially the examples with output.

Something that’s not so focused on the deprecated prototypes, but more on the topic of newcomer friendliness, that has bothered me before, is the lack of basic “recipes” in the current documentation.

When I visit the rendering documentation, I see a lot of technical stuff. I don’t really want to send new colleagues something about fusion file inclusion and all the details (and THEN I see the sub page is called “Fusion in Depth” :melting_face:). To get started quickly, I would expect questions answered like:

  • How do I render something conditional? When should I use @if, a ternary eel expression or one of the fusion prototypes like Match or Case?
  • How do I iterate through items? When would I prefer ${Array.map} over Neos.Fusion:Map? How to use @process in a Loop (or rather into a Map and join afterwards. Or @process the items)
  • How does this work with afx?
  • (maybe special things like “When do I need Neos.Fusion:Value?”)

The other big question, that I see a lot, is about context/this/props which always heavily depends on the used prototypes, so I’m not sure how to approach that. For the points above I personally like this “I need to do X, so I look that up” approach to learning language features, but in some parts fusion feels like I need to know how the language works in depth, so I get the idea of explaining the language itself first.

My perspective isn’t that of a newcomer anymore, so these views are probably debatable, but this thread sounds appropriate.

3 Likes
6

I recently had to work with Neos.Fusion:Loop and had problems because all examples in the reference are using Fusion objects while I was trying to write it using AFX. I think that a sort of extended reference with many examples and variants would have helped quite a bit. Also accessing item-properties inside the loop is only explained in some forum post and I think it is outdated.

So I’m thinking that maybe adding tutorials in a specific section for explaining the usage of Fusion objects in many different situations could be helpful.

7

@mficzel are these removals on the roadmap for v9?

8

Valid point. Will try to make this happen

1 Like
9

Will be happy to look at the PR when you are ready!

10

Here you go: TASK: Remove deprecated Fusion prototypes by mficzel · Pull Request #4537 · neos/neos-development-collection · GitHub

2 Likes