Redesign and restructuring

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:

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)

  1. Meet with @rolandschuetz and other interested people and try to decide what’s next. (Meeting on 22.12.22 at 15:30)
  2. Integrate new design into docs.neos.io
  3. Try to create the structure that explains the basics (see draft) using the already existing content
  4. Try to improve the existing content and fill missing content gaps.
  5. 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.
  6. Improve the documentation reference with better examples (and also previews what gets rendered)
  7. 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:Collection to Neos.Fusion:Loop).
  8. Improve search (something that works as good and fast as algolia docsearch) to match other documentations.
  9. Profit :wink:

Thanks to my employer JvMTECH (@newgen) who allowed me to use a part of my worktime for open source work.

Further reading

How to document?

Relevant discussions

6 Likes

Thank you! I like your initiative.

It might just be a personal preference, but I like your first design much better than the current one. The font is more readable, because it is more narrow. I know, “Work Sans” is the font used by Neos, but may be you can make the code font bolder, that already helps. :slight_smile:
And as a little detailish feedback, I find the icons in the sidebar a bit distracting, for a technical documentation I like it cleaner.

And may be you can also design a new Neos header (the blue bar on top of https://docs.neos.io or https://discuss.neos.io) that fits better into the design and can also be used on https://www.neos.io :grimacing: it would be cool to connect all the neos.io pages with a nice common header. also it is kind of irritating to have external links in the site navigation, better have all the external links in the “Neos World” header. but I guess this is not the main topic here.

btw. is there reason why the “Blog” is not called “News”? I was looking for a release post one, and I would never expect it under “Blog”…

Thank you very much for the feedback. :blush:

I don’t quite understand. My “frist design” is 95% the same as the one in the Neos PR. I just replaced the border radius with the neos edges as requested by the team. Also the font hasn’t really changed. Maybe you need to show me a comparison.

While this would/could be an improvement, it would then be necessary to add this bar on the main neos.io page as well. I think this should be done in a separate “project”.

It is the same name as it is in the blue neos bar. Maybe someone from the marketing guild can answer this.

1 Like

Next steps after meeting with Roland

1 Like

The productive deployment and document tree adjustments will be performed tomorrow, Wednesday, January 25 at noon.

1 Like

We fixed Matomo today, so we can now track any 404 errors etc.

The new docs have lifted off!
https://docs.neos.io :flight_departure:

Now, it follows the restructuring.

All links should still be valid and no content has or is going to be deleted. If you have a problem, report it in #guild-documentation. If you want to help with this effort, I’m open for feedback.

Thanks for all the help so far!
@sebobo, @markusguenther, @kdambekalns, @rolandschuetz, @Marc, @jonnitto & @newgen

5 Likes

Thanks to you for your work!

4 Likes

A thousand thanks for the long breath and all the work. You are really great :slight_smile:

2 Likes