I would like to work on the following aspects. How do we approach this?
Coverage. A lot of questions from the forum could be answered with in the official manual. Either the information is missing or can not be found. (In a Information Architecture sense, not in a technical search engine way.)
Assumptions. Neos features some unique concepts. New users are faced to grasp them efficiently. (Mapping content to nodes, properties, using fusion, eel, flow…) The current manual expects users to be familiar with certain concepts. (Example: If you’re used to WordPress and now are learning or even looking at Neos you will not understand how to build your website. If you’re coming from TYPO3 Fusion will be a natural progression.)
General organisation. Documentation is divided per package. This is a legitimate structure but as a user that installs the “whole CMS” there is only one package: Neos. Either we find a way to guide a user through the individual package docs or we unify them. Possibly just rendering all those single repositories under one domain as separate chapters…
I am personally not really good in writing and structuring great documentation, but I will of course help if I can — at least with answering questions, checking for correctness, …
Regarding tooling: my learning from many years of open source (and various documentation efforts) is, that it is rarely a tooling question. Thus I would propose to stay in our current toolset (restructured Text and readthedocs), and rather focus on content.
I agree with your „centralization“ thinking — so let‘s just focus on putting all the relevant docs in the Neos package… I‘d say this is pragmatic and could work well for now
Just my two cents,
Curious to hear further thoughts,
Sebastian
The tooling refers to tools used for organisation and coordination (e.g. GitHub bugtracker, Trello, Asana…) Currently, there are virtually zero GH issues regarding documentation. Either the docs are perfect—which they are not—or what documentation gets written and how is not coordinated through GitHub.
To be honest: I see many aspects that can and should be improved but that’s too much for one guy. So we need a way communicate in detail the “atomic tasks” regarding documentation.
Ah, I see… I suggest you use the tools that work best for you, though I would have a slight preference for GitHub as it is great for transparency (If I were to organize the effort).
