Funding request: Documentation

The Neos Project Finances & Fundraising
5

Thank you for your thorough write-up. You cover all my personal pain points with the current state of affairs.

We need to clarify our target groups: Users is not specific enough. Are they end users? Customers? Integrators? Developers?

There are two things I disagree:

  1. I don’t know if 15 person-days are enough since we need to double check the new and existing docs. To be clear: Code examples should be actually executed and checked.

  2. Tooling. I’d suggest splitting docs. The developer references (API docs, references in general) should stay in their packages and rendered by ReadTheDocs. Everything else does not make sense to be structured and versioned in the same way.

Let me elaborate on my last point. I assume the following:

  • I define users as everything else than core developers. Mostly integrators, people doing web projects for themselves or clients.
  • Those people do not care how the core team seperates their code or if it’s a mono repo.
  • The user facing documentation should be easy for the users not for the core team.
  • Most of the “non-reference-documentation” does not change much with different releases.
  • Neos users shouldn’t need knowledge about Flow

Therefore I suggest reducing the package documentation to reference material. Everything else should be under docs.neos.io and probably be managed by a Neos instance itself.

Within this new subdomain and Neos instance we should strive to make learning fun by a wise choice of design language, text language and structure.

We should acommodate different styles of learning:

  1. Structured (reading a book from start to finish)
  2. Explorer (well, digging into different chapters as the need arises)

Finally, every package that comes with the default distribution (or is in the Neos GitHub Organisation) should be documented as a whole. As I said before, the user does not care where the code lives but wants to know how to solve their problem.

I really like the simplicity of Phusion Passenger and their docs: https://www.phusionpassenger.com/library/

We should also start generating a list of questions, problems etc out of forum and slack questions. (Like I did here: https://github.com/neos/neos-development-collection/issues/1771 and RFC: How to organize documentation efforts?

My current list of documentation topic ideas: https://trello.com/b/pYNV6iKc/neos-documentation-effort