Based on Spending available 2018 budget, I’d like to bring up funded documentation work as a proposal to spend some of the remaining 2018 money.
- Documentation has been a weak point and a major barrier to adoption of the Neos project ever since I work with Neos.
- It is especially hard for beginners to get started with Neos because of our weaknesses in this area. I base this statement on the experiences and feedback I get from the Neos trainings which I do.
- Good documentation is a must-have if we want to keep attracting users and integrators.
- Documentation is certainly less attrative and “fun” to do than programming/creating features, but just as important.
What exactly do I envision?
- I would like to fund a documentation sprint to improve certain aspects of the current documentation.
- I do not want to change tooling/rewrite the whole thing/change fundamental things about the docs. This doesn’t seem necessary to me, as our tooling actually works quite well and the docs have most of the features documented, it’s just hard to find stuff in there.
Which aspects do I want to focus on?
These are the areas where I see the biggest need for action:
Conceptual basics / Technical principles
To me, this is the biggest issue with the current docs. We explain the individual technologies (Fusion, Fluid, Eel, FlowQuery, Config, NodeTypes, …) pretty well. But there is no point where we explain how the whole thing fits together, and this is also why newbies get confused so quickly. They simply cannot build a mental model of Neos that allows them to understand what Fusion/Fluid/whatever actually does, and why. The Technical Principles section of the docs is empty - this speaks for itself.
There are some structural issues in the docs, such as the duplication between Quickstart and The Definitive Guide in the Flow docs, and a few others. No major rework, but I think we can optimize the structure a bit - again with the focus on where to get started with Neos, and make sure new users understand which guiding thread they are following at all times.
Setup and Installation
I want a clear installation guide that covers the most important use cases, such as local dev, setting up Neos with a webserver (apache/nginx), and setting up Neos on a shared hoster (even though most of us like to have more control over their environment, this is what many agencies/clients use). Again, this is one of the points that many people struggle with, so we really need some improvement here.
The entire UI section is outdated, there is still some Ember stuff in there, and some of it is just plain wrong by now. On the other hand, there is some React UI documentation spread over several chapters (such as https://neos.readthedocs.io/en/stable/ExtendingNeos/CustomEditors.html and https://neos.readthedocs.io/en/stable/Contribute/Code/UI.html and also https://github.com/neos/neos-ui) which needs to be cleaned up. And of course, there is a lot of information missing on how to get started with extending the UI.
Clear up outdated information and bugs
Read through the whole thing once, and remove/fix everything that is wrong and/or too old.
Identify missing parts / “to-be-writtens”
There are still some parts that have a “(to be written)” attached to it since the very beginning. These should be listed (as issues in a Documentation board) so they can be worked on asynchronously after the sprint. These are (incomplete list):
- Logging and Debugging
- Deployment and Administration
I would like to setup a goal where we want to take the docs. The steps above will fix the most pressing current needs, but I’d like to have a vision for the docs set up so we know which steps to take next. A lot of this boils down to reading and understanding https://www.divio.com/blog/documentation/, and answering these questions for each “kind” of documentation mentioned there (and documenting the answers of course )
- Do we already have it? If not, should we?
- Where does it come from (i.e. who do we want to create it? Core team members, community, …)?
- Where should it be (readthedocs, neos.io, external websites, forum, stackoverflow, …)
- How do we make sure users find it?
- How do we make sure docs contributors can easily add new things?
- maybe more - we’ll figure that out when we do it.
First ideas regarding that “future direction” are already being discussed here.
What will it cost?
I estimate that we can get the points above done really well with about 15 person-days of work. Based on the hourly rate of 100€ that Christian suggested in the release thread, that would mean spending 12.000€ of our piggy bank on docs.
We can, of course, tackle only parts of the points mentioned above - e.g. I estimate that the much-needed technical principles section could be completed in 3 days.
How do we proceed?
Let’s discuss this some. Where do you see the biggest issues with the current docs? Should we do them in addition or instead of some of the points above? Do you think my time estimate is realistic? Do you think it is viable to spend money on docs at all?
[EDIT: Added a section regarding the UI docs.]