Restructuring the Neos Documentation

Creating Neos & Flow Documentation
1

The current documentation covers many use cases and has a lot of useful informations. But it is often hard to find the information.

We suggest to alter the structure of the documentation like so:

  1. Getting Started -> is targeted at decision makers who want to check neos out. It should provide all the information needed to get the demo site running and point out the unique feature neos offers technical wise.
  2. Technical Principles -> is targeted at developers who want to get a grasp on the key components and technologies included in neos. It offers a short introduction to each “buzzword” together with a link.
  3. User Guide -> contains the end-user documentation that is mainly about the structure of the backend and the modules there.
  4. Creating a Site -> all the informations an integrator needs to setup
    neos. No line of php goes in here but a basic 1.2.3 guide for
    creating a neos website is added.
  5. Extending Neos -> Documentation of the intended ways to extend neos
    beyond what is possible by configuration. The range is from
    DataSources to Custom Editors, Eel Helpers or even the integration
    of a Flow Package.
  6. Inside of Neos -> In depth explanation of the infrastructure of
    neos. Covering Backend and Frontend.
  7. References -> Autogenerated Documentation for ViewHelpers,
    EelHelpers Typoscript etc. from all Packages that are in a default
    (Demo Package) Setup.
  8. Contribute -> Link to the webpage
  9. How Tos -> Examples of common use cases plus a section of Best Practices.
  10. Running Neos -> All kind of Informations regarding the
    Installation and Deployment and Maintenance of Neos.
  11. Appendixes -> Contributers, ChangeLogs, ReleaseNotes …

In a first step we plan to move the existing documentation into this structure. Later on we want to begin filling the gaps by priority and to add cross references where it makes sense.

The Jira-Ticket: https://jira.neos.io/browse/NEOS-1376

6 Likes
2

:santa: :thumbsup: That sounds like Christmas!

I really like what all of you came up with. Renaming the different parts of the manual so that they describe the contents instead of the user role they’re targeting makes a big difference. I’ve tried to think of ways to help people understand what an “integrator” is, but this completely sidesteps the issue. Wonderful!

Also, moving the References out of the Appendices is a good step.

Also, for the getting started section, we should have a preloaded vagrant box or docker or something that people can download, or point them to a demo website to learn about the features of Neos. Learning about the setup and the environment is not important, except for knowing generally what is possible.

I’m not sure about the name “Running Neos”, but something about installation, deployment, & maintenance will be good. I wonder if we can have one guide for both Neos and Flow? Or, could we have several parts of the guide that are the same, but customize others? (ReStructured Text can include other docs)

In any case, I say let’s go for it.