Hey Roland, thanks for chiming in.
What I mainly fear is that the documentation will too easily be outdated. Especially the parts that go into implementation details. We already have this issue as is and I think completely having everything in a Neos instance will make it even worse. Optimally I think that the most basic, low-level and technical documentation about features should live in git and side-by-side with the actual code. Even now, with the docs in git but seperated by an abritrary folder structure leads to documents often not reflecting the actual state of affairs, code examples getting outdated etc.
From a maintenance PoV every new feature or change of existing feature should always be delivered together with proper documentation describing it. From my experience though, humans tend to be bad with keeping separated processes in sync manually.
My wish would be to somehow connect both worlds, have a redacted and enriched documentation in Neos which pulls in parts from a living documentation inside git. However this could be achieved is up to be discussed (may be a node type that fetches an rST/md file from git and renders it?), but I think this would improve things a lot.
Also, what I’m not sure how it is handled currently: what about docs for different versions of the system? e.g. old ui/new ui, future old CR/new ES CR? If there is a solution on how to deal with that, is it documented?
As said, I totally love the efforts you and the others did up to now with docs.neos.io, it is so so much better than before. I still think there are a couple of things we could improve further to make sure the documentation will at minimum keep at this level in the long run and hence why we should think about sustainable processes, that are as tidy and straightforward as possible. So I’d love to see some budget to get this rolling!
The publish workflow can be drastically improved, a form on the docs website could automatically create a new user with a separate review workspace. As soon as the editor published his changes we already get an email and can review and publish those changes. So there would be the same amount of manual steps as a git merge.
Is this already in place? If not, that would be another great topic for getting done with a budget
I started a Guide Tour a long time ago, but than the docs project happend. If anyone wants to work on it: https://github.com/rolandschuetz/neos-guidedtour
Looks like some solid base!