Hi all, I’m looking for the right documentation for me…
I woukd really like to get to know NEOS deeply to be able to use it for most projects. But unfortunately this ist not possible for me at the moment. I tried to get into it but it just takes too much time. I’m extremly missing a wide and deep top-down documentation to learn how this complex works.
For me the given documentation does’nt work. It’s not deep and wide enough. Many times there are examples but you don’t really learn the clou behind it so most times I’m not able to solve the next problem on my own. Following common words describe it rather good:
“Give a man a fish and you feed him for a day. Teach a man to fish and you feed him for a lifetime.”
I just get some fishes out of the available documentation but I don’t learn how to fish. I hardly looked for any documentation as well as books to buy. But there is nothing for my needs. I found that @christianm and Patrick Lobacher started to write a book. Maybe this would help but it’s not yet available.
Is there anyone who has the same problems und could give me some helpful hints?
To make clear. I don’t want to bash the available documentation. I know how much effort it takes. But it just doesn’t qualify me enough in an acceptable time.
It takes 10.000 hours to become a expert at something - so it takes 10.000 tries with the fishing to be really good at it Joke aside, “learning” is a very sensitive subject, as we might not all share the same “best way” of learning.
So, since a part of this year budget has been given to the work on documentation (Funding request: Documentation) your idea of “top-down documentation” to explain the concept would perhaps serve usefull for the documentation development.
Maybe they already have a plan about more “get started” material - I can’t tell. But I will suggest that you take the good ideas you have and share it with for example @beheist .
To share a personal view on how to get to learn Flow, Neos and Fusion (The three building blocks) I can suggest that you install the Neos.Demo package and look at/browse through that while reading the existing documentation material. And be curious! Don’t be afraid to fail - actually, be more afraid of not failing! And ask! All questions - nothing is newbie, we are all started at some point where we didn’t know everything
But it takes less than 1000 tries if someone told you wich time, wich place and which lure.
Of course people prefer different styles of documentation. That’s why I wrote “for me”. E.g. in 99% I preferred books from Addison-Wesley while other persons liked O’Reilly.
I already tried to get into the system deep enough by installing the demo project and try and fail. And here, if you compare it to the fishs, it also would take less than 1000 tries and fails, if I already had a clear insight. The problem is that I can’t invest unlimited time. That’s why I searched for docs pushing me forward faster. But I Didn’ find them, functioning for me. As I also looked for puchasable books you can see that it doesn’t have to be free of cost. It just must be affordable and lead to an acceptable invest of time.
thanks for your input! Yes, we are very aware that the current documentation leaves a lot to be desired, which is why we are getting a docs sprint setup right now. We’re very grateful for any input that you have, be it specific parts of the docs that didn’t work for you or any ideas on how to structure the docs. If you want to get involved, please join our Slack in #guild-documentation
I think that I understand what you mean …
The dynamics of developing Neos was so agile, that docs couldn’t follow any more.
Explanation of Key-Topics is really missing, - so coming from outside you are simply lost … (if you want to gain deep knowledge just over docs) Nevertheless a lot of documentation work have been done, and the ‘FlowFramework’ Documentation proves a fantastic ‘deep-top-down’ oeuvre … (my personal point of view …) https://flowframework.readthedocs.io/en/stable/TheDefinitiveGuide/PartIII/index.html
As you described, the Neos documentation lacks this level until today, - but the problem has been identified … (as Bastian mentioned already)
I just stumbled over an ‘orphan’ tutorial concerning ‘Fusion’ these days, that may help you eventually … https://learn-neos.com/blog/hitchhikers-guide-to-typoscript-2-part1.html
@chkoeppel: THX
The documentation you mentionend is just one part of the hole system. It would be good to have these docs linked within a documentation explaning NEOS.
I give an example (also for @sorenmalling and @beheist):
There is no doc explaining the complete rendering process for a NEOS request. If I would understand what is happening there it would be quite easy to start developing. But from the current docs I never know my complete surrounding. I just see the next wall but not the room or even the house.
More details, there is this graphic in the current documentation:
How does NEOS get the request and to which process is it forwarded?
When we are in a document node certain processes must have been finished. Which ones? Where am I in the rendering stack? What is my surrounding? Which objects of which system parts do I have access to? …
When I am in the fusion part same questions as above. So much must have been happened. It’s not only fusion that have to know at this time. I have to know where I am and to which objects or system parts I do have access.
Fluid of course same subject.
Documentation of Flow, Fusion, Fluid and so on is just a subpart.
This is just a small example but shall explain the blindness with which I’m walking through the NEOS complex. It is not possible for me to get this knowledge just by try and fail in an accetable time. And as I want to use the system for client projects I cannot just start and look how long it takes.
Thank you very much @Martelinho for this valuable feedback! And please, if possible for you in any way, keep up with that, try to learn Neos together with the team and tell us where you hit a road and why.
The biggest issue with writing comprehensive documentation is often times that as someone that is already deep into the matter, you won’t see the wood for the trees. This can only be solved by an outsider willing to explain where things are not obvious enough, not explained broadly enough or too detailed and ask questions. And it is really hard finding someone like that. And then you showed up with perfect timing, since as already mentioned the team is up with a budget to work very focused exactly on that topic!
So please help us out with a bit of your time and I’m sure you’ll be able to learn A LOT about Neos very quickly. Talk to the #guild-documentation folks and maybe think about visiting the documentation sprint.
Hey there, I‘m one of those #guild-documentation guys and we‘ll be working during a documentation sprint in december on those issues.
If you want to help us you can tell us what you mindframe is. You have assumtions on how things might work and get frustrated when this turns out to be false. Tell me about those questions and assumptions and I will try to clarify those in a future version of our docs.
Hi all (@sorenmalling, @beheist, @chkoeppel, @aberl, @mstoyanov).
First thanks for your answers and open mind. Seems that this subject has high prio at the moment. So maybe it was a good time for my “cry for help”.
I have to underline again that I can really understand why documentation sometimes don’t work for those people that it is written for. And I know that the reasons are not missing efforts or elaborateness.
Since currently I’m working for several projects I will not be able to join outside meetings or spend many hours a day. But I’m willing to help you. If and how this is possible also depends on what your plans are concerning topics and schedule. If it is possible it would be the best start to talk to one person on the telephone to find out how it could work. So feel free to contact me by message for the next steps.
I actuall like the idea of having a deep-dive around the question “How Neos renders a document node”. This actually goes through a lot of layers in the system, where each part does only a particular (and interesting) thing. On each layer you have ways to configure or extend the system to act in a different way.
Also there are quite some packages involved in that process.
Only knowing about all the layers and extensibility points - and the best practices for common requiremenets - makes you proficient for new tasks.
Where in the learning process are you now and what is by now your view on the current state of the documentation of these aspects?
Would you be able to share / contribute insight you’ve gained?
I tried to get deeper into the system by developing a small customer project. I finally got the project working together with the help of the community. I unfortunately came to the result that it is not the right time for me to focus on the system. It would require too much time compared to the possible earnigs. But this is just the situation for my person and my available time and can be differnet for someone else.
Joke aside, “learning” is a very sensitive subject, as we might not all share the same “best way” of learning.
But it takes less than 1000 tries if someone told you wich time, wich place and which lure. 
