NeosCon 2023
How did this all happen?
In autumn 2021, as part of the application process as a frontend developer, I had to complete a task involving fusion. Then in May 2022, I started to develop Neos sites. I struggled to understand many aspects of the whole ecosystem. As I don’t like learning with videos, I tried to get started with the documentation and I quickly got lost.
I had so many questions as to how and why, which were not answered in the documentation or the reference. As a frontend developer, coding components for a living, I was mostly looking for fusion and afx. Googling didn’t help either as the results were not helpful, covered unrelated content or showed many [READ-ONLY] repositories.
I was confused by all this. I have already used mono repositories, but I have never encountered such mirrors. Somehow it seemed that there was a ton of information, but it was all over the place and I didn’t know were to look.
What did I do?
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 and found easy to learn (aka the vue docs).
I tried to improve the documentation from a beginner perspective and wrote what I personally needed to fully understand the whole ecosystem from content repository to fusion rendering.
First draft (VitePress)
In May 2022, I created a new docs design and structure using VitePress and markdown files, as this enabled me to focus on the essential parts of the content and structure. The feedback on my draft was 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 the positive feedback, I began implementing the design of the draft into the neos docs repository. I started with 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. Therefore, my new structure relies on a more verbose sidebar where you can see subpages without a page load.
In addition to the new design, I tried to solve the following things that I also find important for a documentation:
- CSS & JS Pagespeed
- AFX, Fusion & Eel Syntax Highlighting
- Integrated examples
- Accessibility
Release
With the help of the Neos team, I was able to release the new design and structure in the neos docs repository in January 2023. The next steps are to integrate the api reference, improve the content, add a good search and more examples. Eventually the structure should match my initial draft.
Award
I got a lot of positive feedback for my work on the documentation, and I am happy that I could help the community with my contribution. Receiving the Neos Community Award at the NeosCon 2023 came as a surprise to me and I feel very honored. Thank you!