We discussed how the Neos project could benefit from this guide and are suggesting the following steps:
We remove the “user guide” section from readthedocs and put it in neos.io instead. This applies ONLY to the end-user facing documentation - developer docs will remain on RTD and english only.
The “Docs & Support” Section will have 4 Parts in the future:
End User Guide -> the part which is removed from the RTD docs
Developer Guide -> today’s “Documentation”
API Documentation -> stays as it is
Support -> stays as it is
We enable a language dimension for neos.io and translate the “End User Guide” section only. The rest of neos.io remains english. We display a language switcher and/or links to the different language versions of the user guide on the “End User Guide” page and its subpages.
And lastly: We take over Roland’s awesome German user guide, update the English one and have a fantastic resource which we can point our customers to, making it easy for them to get started using Neos, which is the point of all this
Please give us feedback if you have any additions or would like to suggest other options!
The current editor documentation is not accessible to non-developers since it does not explain most fundamentals and is mostly a reference list. I developed an in-depth explanation of core principals for typical Neos clients in German. I would like to contribute this to the Neos community and also add an English version.
Neos.io currently doesn’t support all our needs for a documentation page, @beheist and I will extend the website with a new page type DocumentationPage and a few new content node types.
The current state of the documentation can be found in the neos.io workspace “Editor Documentation” and the status of the development in this Slack #guild-documentation post
The way I’m currently writing the editor documentation:
I try to avoid Neos developer-spefic naming like “nodes” and have the documentation as accessible as possible for editors without much tech background.
I aim to have a light tone and things like “It won’t be more complicated, promised”
I explain the simplest way to achieve things (not always the fastest) to keep the documentation easy to understand.
Where I’m not sure:
In many cases, Neos itself has one way of doing it, but with a common extension, it was a different way (neos/seo or neos/redirecthandler-neosadapter).
We could handle this by describing the plain Neos way, or buy saying things like:
If you change the URL path segment of your page, the old URL will not work anymore and the page will be only available through the new URL. If your developer installed the extension neos/redirecthandler-neosadapter redirect urls with be automatically created.
The downside of this approach is that it now includes technical things, the editors won’t know. So they need to ask the developers how it’s handled, … if we just leave this out the docu is less detailed, but easier to access.
I’d suggest that we document the Neos standard behavior, but put some sort of callout-box in place that informs the authors in non-technical terms that there is an addon that changes this behavior or adds functionality - basically as you suggested above. We could phrase it like this:
The optional Neos package "Neos Redirect Handler" can automatically create
redirects if you change your pages` URL path segments. If it is installed, your
website visitors are redirected from the old to the new URL of a page automatically.
If it is not installed, the page will not be reachable anymore under the old URL.
If you are not sure whether this extension is installed, ask your website agency or
your project manager.
I’d not use the technical name (neos/redirecthandler-neosadapter) but rather a user-understandable one that is at least somewhat self-explanatory.
I think we should explain the features of the packages in the neos-namespace as „Neos feature“ but mention wich of those require an „optional package“ like forms / redirecthandler / node-types etc. with a standardized info-box as suggested above.
Making the distinction along the lines of the base-distribution would exclude interesting stuff like formbuilder and skip needed info-boxes for packages that are in the base-distribution but are often removed.
In destinction to „neos feature“ i suggest to use the terms „community feature“ or „community package“ whenever packages from other namespaces like flowpack are needed. This might be not relevant for the editor documentation but for other docs.
Thanks for the feedback. The full content is now added in German and English in the neos.io workspace “editor-documentation”. Just the translated images are missing. Today I will improve the layout coding, so that we can release it this week.
I am now using the packages Neos.SEO and Neos.RedirectHandlerNeosAdapter as default packages in the documentation.
I am happy to announce our all new documentation for editors. It is beginner-friendly to help editors start with Neos. We have an English and a German version, with a total of 13 000 words and helpful screenshots. Starting from the very basics or Neos. It also explains common challenges like the difference between paragraphs and line breaks.
The goals of the documentation is that you can give this to your customers to get familiar with Neos. Any additions and improvements are welcome!
multi lingual user guides is awesome idea. I would love to give users possibility for reeding the user guide in any form(paper, etc) and place(neos.io or google docs) in native language.
glad you like the new user guide.
We deliberately decided to create the guide on neos.io because of the possibilities we have there with regards to customization, interactive elements, various styles etc, all of which is not possible or very inconvenient on RTD.
You’re absolutely right Markus, package is the right term. Fixed it above. Also adding alink is a good idea.