Ideas for future direction of the docs


(Bastian Heist) #1

This thread is a collection / discussion of ideas regarding the future direction of the Neos documentation. It started off in this thread, and I’m reposting the first two messages here to keep the other ones focused.


Funding request: Documentation
Funding request: Documentation
(Bastian Heist) #2

Christoph Köppel (@chkoeppel) 21h
(original: Funding request: Documentation)
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

“code-centric” Docs-Space
“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 compacted the idea in the following paper:
https://drive.google.com/file/d/1YwbkkuYpdaI0YWKcD9wAmzS7qZa8bJ08/view 1
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” …


(Bastian Heist) #3

Max-Milan Stoyanov (@mstoyanov) 16h
(original: Funding request: Documentation)

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


(Christoph Köppel) #4

Hi Max-Milan

to find out if we understand each other, - I continue some reflections related to your posts …
Hereinafter I talk of “user-centric Docs

  • mainly tutorials, how-to’s, etc

(code-centric Docs are well regulated in the coding dynamic).

… the information is missing or can not be found. (In a Information Architecture sense, not in a technical search engine way.) …

  • the “Docs-Space” shall be well structured. There has to be found a “Tree” that reflects the whole domain.

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

  • User-centric Docs-Space has many more perspectives than code-centric Docs, - as you point out …
  • there are multiple aspects, that are located “beside” the specific code-topic
  • specific topics (like ‘Configuration’) can be treated as a ‘overview main topic’ (overview can enlighten specific understanding)

The user facing documentation should be easy for the users, - not for the core team.

  • that’s the point, - for a developer, it’s really not easy to put oneself in the skin of the “normal” user …
  • therefore user-centric docs can be covered by people on the ‘user side’ …

Most of the “non-reference-documentation” does not change much with different releases.

  • I agree … that user-centric Docs behave more tolerant over time

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

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

Coming finally to your list (… that is still a list :wink: ) …

Conclusion

  • I don’t think that we will find a way to animate or force people to write all these tutorialson command
  • everybody involved in this project would like to see those tutorials though …
  • many approaches have been done in the past, but …
    (http://www.planetflow.net/ … was one of them, no ?)

Thats why I still tend to convince, that we need a structural solution

  • arrange a structured space to range ‘individual’ efforts in the right place

  • tutorial space would become more dynamic, and selective contributions may rise …

Example: https://symfony.com/doc/current/translation.html

These 3 articles could be ranged properly in the “user-centric-Doc-Space” and there would not only be 3, but maybe even more ‘micro-tutorials’ and they would be ruled by an intelligent Tool, to let this content be ranged (maintained) over time …

Why not using Neos Content Management ?
Neos is a tool that would perfectly match the conditions to manage and rule such a user-centric “Docs-Repository

Frankly, I don’t see the chance, that anyone will do this task by hand

  • doing reviews all day from morning to evening …
  • and don’t forget that turorials are mostly more emotional and individual than code-centric docs, - which is not negative itself … (but …)

So Max-Milan, - do you still see the problem (Tutorials) as a lack of individual efforts, or the need of a structural solution ?


(Max-Milan Stoyanov) #5

Wow. I think we are working towards the same direction. There may be some detailed differences (sematics, naming…) which we could work out in a chat or hangouts session.

We need a structural solution to this problem. I would like us to work out a concrete solution that we can propose to the community.

Referring to the Robert’s user docs: The official Neos design makes learning boring but the original CodeQ is far better. :wink:


(Christoph Köppel) #6

Hi Max-Milan

glad to hear, that you think in the same direction …
I resume:

a structured Docs-Repository could be a solution ?

  • includes a ‘closed’ part that mainly references the historically grown Neos Code-Docs

  • includes an ‘open’ part where users can easily contribute their microTutorials, HowTo’s, share typical codeSamples, …

’Workspace’
… link to Workspace on Google-Drive …

I created sort of ‘open’ workspace, where the main conceptual lines are described again in some few papers
(feel free to add/modify or whatever you want …)

  • project requirements (roughly)
  • general proposal
  • layout idea and rough mapping

You may read these 3 papers and think about how realistic would be a technical implementation with Neos CMS
(how much time to implement ? … funding ?)
You may think about the design of Roland Schütz, maybe he would be the right guy to discuss …? (experience)

I’m sure, you have the technical skills to evaluate, realize these things …
My problem is, that I’m not from software industries and have very small experience with Neos technologies (naming,terms) … so may be difficult to discuss with me … ? :sweat_smile:
But I’m open, if you want to discuss / chat with me … (conceptual parts)
Be aware that ‘community’ does not feel to much attracted by the “Docs” topic.
So, keep cool and don’t get frustrated if things would get stalled somehow. :slightly_smiling_face:


(Bastian Heist) #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:


(Roland Schütz) #8

I think by building a platform we are doing what we like to do (coding) instead of solving the real problem (the boring work of writing documentation).

We do not have a bad documentation because of missing tools, but because no one writes and maintains documentation.


(Max-Milan Stoyanov) #9

Technology is never the answer.

I know this. I want to change the technology and the content at the same time because it helps to refocus the content. Basically, we make use of Content Strategy methodologies and create a new learning environment.

  1. We create a content inventory and rate the existing content:
    Is it up to date?
    Is it relevant for the target group?
    Is it comprehensible?
    Is it fun?
    Is it grammatically and formally correct?
    It it achieving it’s goal?

  2. We identify gaps in our documentation.

  3. Create a table of contents and a semantic content structure.

  4. We find a way to track work for creating new content and improving existing.
    We need to create single tasks that do not require than one hour of work.
    This would result in more participation because you don’t have to first identify what to work on, where to put it…
    Domain experts (core developers) could write up a quick and dirty draft. Later those are reworked by others.

Those four steps are independent from the underlying technology.

The docs.neos.io space would house a simple Neos instance.

  • It does not make use of dimensions for versions.
    I don’t think we need those right away and simply noting a change or deprecation may be enough. Only add complexity when needed.

  • It will not use the design from the main neos.io site package.
    The current design language (most notably type setting, font size, color, contrast) does not enable fast, fun and efficient reading or learning. Together with Roland‘s expertise we will create a new theme while keeping a connection to the Neos brand guidelines.

  • It will not house a dedicated user created section.
    Those can be contributed and be integrated into the official table of contents. We may skip user involvement at this stage.

This would focus the process on content and not technology. The docs Neos instance will be simple and easy to setup. It will be a tool and a basis and can not replace (re-)writing documentation, tutorial, references, how-tos…

I need to say it again: Technology does not improve our docs automatically. Writing does. Tracking work and lowering the barrier for non coders to (re-) write does.

I want to create processes that foster good documentation.


(Max-Milan Stoyanov) #10

I just had a look at your documents. I think the mechanics and technology you describe can and should be handled by Neos. Those features would really lift the documentation experience for our users to a next level.

Time and energy is limited so we should focus IMHO on the tasks with the most impact. I propose using a simple Neos instace for our documentation and going from there in incremental steps.

As I said before: We are working in the same direction. You describe the optimal state and I try to find the next steps. If we solve our content problems we can tackle more advanced documentation features.


(Christoph Köppel) #11

Your summary above sounds really concise and corresponds to my personal experience

  • that writing tutorials can be really inspiring and satisfying, even for oneself …

  • if there doesn’t exist an appropriate platform, - the “illumination” remains obscur anyway …
    (… without knowing if others would have benefited too …)

So if you find an approach that fits your time and energy budget, - I’m confident that your decisions will point into the right direction … and produce realistic impact.


(Roland Schütz) #12

Doing this kind of work is way more complicated than it first seems. Just writing the editor documentation (translated in DE & EN) was more than 100 hours of work on my side and then my designer Mato and Bastian were also doing additional work.

So if we really are going to do this, let’s do a Slack group call to discuss details.


(Bastian Heist) #13

So, for anyone else following this: There is now a #project-future-docs channel on Slack and we will have our first call on Wednesday, 14:30 CEST, to discuss how to move forward. Anyone is welcome to join!