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: