Funding request: Documentation


(Bastian Heist) #1

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.

Why?

  • 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.

  • Structure
    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.

  • UI
    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):

    • Testing
    • Logging and Debugging
    • Deployment and Administration
  • Future direction
    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 :wink: )

    • 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.]


(David Sporer) #2

That’s a great idea but I’d like to add one thing I think is very important (especially for the Flow docs):
close the missing gaps! There are still some parts that have a “(to be written)” attached to it since the very beginning like Testing, Logging and Debugging and Deployment and Administration.


(Bastian Heist) #3

Hey David, thank you for your input. I agree that these are also important, but not critical right now. My suggestion would be to list and prioritize these and work on them asynchronously. I added a section above regarding listing these missing parts and getting them in a board so we can work on them.
Of course, if the team considers them critical, we can extend the sprint accordingly.


(Christoph Köppel) #4

Hi Bastian

as you summarized quite well the topic, - it inspired me to some further reflections.
Shouldn’t the “Neos Docs space” probably be separated into

  1. code-centric” Docs-Space
  2. user-centric” Docs-Space

The first is no problem, and should be maintainable like code …

  • as you initiate it right now …

The second would cover ‘users need’ of ‘having’ tutorials, how-to’s, …

… but how to

  • have them produced (the others)
  • standardize their appearance (form)
  • place them (where to find)
  • regulate them (quality)
  • maintain them (or not maintained)

Proposal: Repository for "user-centric Docs"

I don’t think, that there were a tool on the market, that would cover this topic, but ‘Neos’ could cover it technically

  • page tree as ‘configured’ global “Doc reference layer”
  • dynamic nodeType-Module (illustrated content)
  • filter logic
  • user access and edit-constraints
  • handy filter template
  • “comment” module

Such a tool would not be made in one day, - I know …

  • How much time to develop for somebody who has the skills ?

  • if the idea would be realistic, - should it be taken in the budget consideration now ?

  • “user-centric docs” themselves would never get paid, I think … because this would be endless … ?

But if you count the endless hours for “classic” scenarios concerning “production and maintenance of user-centric documentation” …

Could at least be worth to gain overview now over the topic, just to understand the vastness of the “Docs-Space”


Ideas for future direction of the docs
(Max-Milan Stoyanov) #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


Ideas for future direction of the docs
(Max-Milan Stoyanov) #6

I am not sure I understand you correctly but it seems you have similar thoughts.
Please have a look at my post and talk about how those ideas could work together.


(Bastian Heist) #7

Hey Christoph and Max-Milan,

thanks for your suggestions and ideas regarding the docs, I’m very happy that there are people who want to get engaged in this area of Neos,
However, please let us keep this thread focused on the question of whether or not there should be a funded documentation sprint. The ideas you have brought up are part of what I envision as the discussion around “Future direction”. Therefore, I suggest moving them to this new thread which we can then use as a basis for that discussion.


(Max-Milan Stoyanov) #8

Just for understanding how exactly fuding requests work: Does it make a difference what exactly should be done to be accepted? Or is the general outline more important?

If it’s the latter you were right by moving our discussion.


(Bastian Waidelich) #9

One of our shared values is trust. The funding request is not a contract but it should outline the intentions and expected outcome. If the latter needs further discussions or is too abstract, I’d suggest to split up the funding request and/or start with an evaluation project. Or discuss it here of course, but I appreciate that the detailed discussion was moved to a different thread