This thread serves as a preparation for the call/discussion on 22.12.22 15:30 CET on my docs effort. Besides my motivation and work, this post mentions further reading and relevant links.
Who am I?
I’m a frontend developer from Switzerland. I’m 27 and started web development at a young age. After gymnasium and a computer science apprenticeship, I worked for various companies using JSP, Wordpress, Symfony & Angular. I then went on to study a bachelor in design and financed my studies with Wordpress themes and Symfony apps. In my free time, I help develop the new version of the popular open source camp planing tool (FE made with Vue). My strengths lie in HTML, CSS & JS. I love to make information accessible to all - through good design, accessibility and structure.
How did this all happen?
In the fall of 2021, as part of the application process as a frontend dev, I had to complete a task involving fusion. Then in May 2022, I started to develop neos sites.
Sadly I struggled to understand many aspects of the whole ecosystem. As I don’t like learning with videos, I tried to start with the docs and got lost pretty quick.
I had so many questions as to how/why, which the docs nor the reference could answer me. Besides that, googling for problems did not really help as the results were either not helpful or other frameworks named similar.
As a frontend dev, that made components for my living, I was mostly concerned with fusion and afx. After the docs were not helpful, I tried googling and found several [READ-ONLY] repositories. I was confused by this. I’ve already encountered and developed in mono repositories. But I’ve never encountered such mirrors. Somehow, it seemed that there was ton of information. But it was all over the place and I did not know were to look.
What did I do?
So I set out to grasp what fusion really is and how it actually works and doesn’t work. My strategy was to press it in a new form I was familiar with, respectively I found easy to learn (aka. the vue docs). I tried to “improve” the docs from a beginner perspective / wrote what I would personally need to fully understand the whole ecosystem from Content Repository to Fusion Rendering.
First draft (vitepress)
In may 2022 I created a new docs design/structure using the old vitepress v0.22.4 and markdown files, as this let me focus on the essential parts of the content/structure. The feedback on my draft was quite positive.
Relevant pages:
- Introduction and Sidebar
- Tutorials
- Examples
- Quickstart
- Syntax of fusion
- API reference with examples and result preview
New design (Neos)
After my initial experiments and positive feedback I began implementing the design of the draft into the neos docs repository. I started from the design of the old vitepress theme and iterated on it. This step was crucial to me, as the current neos docs visual structure and design was not explicit enough for me. Because my new structure relies on a more verbose sidebar (where you can see subitems without a page load)
Besides the design, I’ve tried to solve additional things, that I find important for a documentation:
- CSS & JS Pagespeed
- AFX, Fusion & Eel Syntax Highlighting (currently not working in iOS Safari because the feature has not yet landed)
- Integrated examples
- Accessibility
What should happen next? (in my opinion)
- Meet with @rolandschuetz and other interested people and try to decide what’s next. (Meeting on 22.12.22 at 15:30)
- Integrate new design into docs.neos.io
- Try to create the structure that explains the basics (see draft) using the already existing content
- Try to improve the existing content and fill missing content gaps.
- Integrate the reference more tightly into the docs (while also trying to move the code documentation next to the actual fusion/afx source code implementations) so that the search on the docs.neos.io site also finds items like Neos.Fusion:Loop.
- Improve the documentation reference with better examples (and also previews what gets rendered)
- With the reference integration into docs.neos.io, add howto guides/tutorials/explanations to the entries (e.g. explain why we moved from
Neos.Fusion:CollectiontoNeos.Fusion:Loop). - Improve search (something that works as good and fast as algolia docsearch) to match other documentations.
- Profit
Thanks to my employer JvMTECH (@newgen) who allowed me to use a part of my worktime for open source work.
it would be cool to connect all the 
Implement change requests
