Ideas for future direction of the docs

The Neos Project Project Documentation
7

Heys guys,

thanks for your input so far. I very much appreciate it! I agree that the documentation is in some dire need of major/structural refactoring, so let’s discuss that.

The idea of a documentation portal (e.g. docs.neos.io) sounds very promising, I could see us getting some real benefits out of that. The example you posted is awesome - it makes the documentation accessible and searchable to all target groups. If we build a documentation portal for Neos, it could look very much like that.

Let me explain what the process looks like, if we want to get a decision and move forward. We discuss this some more, hearing the opinions of interested parties. Some of the Neos team members are on holiday or otherwise occupied right now, so we should keep the dicussion going at least until the end of September. Once we have heard everyone and there is still the feeling that it’s a good idea to move forward with a docs portal, we will work out an RFC and ask the team to decide on whether we do that or not. If the team decides that it should be done, we can start moving forward, finding more contributors and building a prototype.

Let’s discuss some pros and cons.

We will need these as a basis for an RFC, to get an agreement among the Neos team. Advantages of moving away from ReadTheDocs would be:

  • We can organize and structure the docs more freely, which is extremely important to cater for different target groups - see the example posted above, that does it excellently.
  • More liberty in design and graphical appeal - RTD looks plain at the very best, and it’s hard to embed images and charts, not even mentioning javascript. Also proper syntax highlighting for Fusion and maybe even an inline REPL are possible.
  • Get rid of the rST docs format - many editors do not like it.
  • Easier docs creation workflow. You log into Neos and change stuff instead of getting sphinx (the rST-renderer needed to build/test the docs locally) up and running, which can be a major PITA.
  • User-contributed docs are much easier to integrate. Neos could accomodate a user-contributed docs space easily with a specially configured editor role and some review processes. Getting high-quality user-contributed tutorials is, for me, one of the biggest pro arguments.
  • RTD itself is a pain to handle, and has been the cause for delays and issues with the documentation in the past (e.g. the rendering not working and delaying the release of the docs for Neos 4.0 for several days)
  • The liberty to add new features to the docs platform, e.g. I envision an error message directory that provides instant help when you search for a certain message code.

There are some downsides, too:

  • A new and shiny docs platform is not going to guarantee better docs. The structure of the docs themselves still has to be reworked and the docs have to be written.
  • We lose automatic versioning of documentation from GitHub. This is probably more important for the reference-type docs. You suggested keeping them on RTD, which sounds sensible. Everything else is likely not going to change that often, and we could use dimensions with fallbacks to maintain versions for different Neos releases. That, however, means that release management also needs to take care of creating the docs in a structured way and releasing them at the right time.
  • We cannot see who changed what anymore (at least until the EventSourced CR is here) - we lose all version history.
  • The platform itself has to be built, which is a certain effort. We could make that easier by re-using the site package from neos.io as a start.
  • The platform has to be maintained, deployed, and monitored, which adds additional effort to our already thinly-stretched infrastructure team.
  • If we want user-contributed documentation, there needs to be a team of people who continuously review the new ones.

There are probably more - please read and think these through and add your own thoughts, as I wouldn’t want us to get all excited only to discover that there are massive disadvantages we didn’t think about.

What should the documentation portal contain?

Pretty much what you wrote above:

  • The “official” docs. In the well-known Divio schematic, these would be References (possibly crosslinked to RTD) and Explanation-type docs.
  • The “user-space” - these would be a curated set of How-Tos and Tutorials, classified by topic, experience level, Neos version, and so on. We would give Neos logins to interested parties and let them write tutorials directly on the site, reviewing them using the workspace functionality of Neos.
  • Possibly more functionality we haven’t yet thought of.

I would like to hear the opinions of @kdambekalns and @christianm here, as we have discussed this in the past and at least Christian has been against moving away from RTD. Also Karsten is afaik the one who knows the docs workflo / RTD platform best from a technical side. Also, @rolandschuetz as he is very interested in the docs topic and has created the fantastic editor documentation. I’d like you to chime in and provide your point of view :slight_smile: