[Neos] Neos documentation improvements meeting notes

[Bastian Waidelich]

Hey list,

Upon Thomas Hempels initiative we had a very constructive meeting on how 
to improve the Neos documentation:

Participants: Christian, Jacob, Karsten, Martin, Thomas, Bastian

The first thing we could immediately agree upon was the fact that we 
have to lower the barriers for contribution, making it radically easier 
to improve documentation in order to leverage the power of the community.

An obvious measure would be to move documentation to github like the CMS 
team already did partly (http://docs.typo3.org/typo3cms/drafts/github/).
That would allow for a much simpler workflow based on Pull Requests.
It raises a couple of questions though:
* Should the documentation part of packages just be *mirrored* or 
*moved* to github
   -> mirroring would require a bi-directional sync which wouldn't be a 
big issue technically but could be confusing & error prone
   -> Jacob also mentioned http://gerrithub.io/ as a possible solution 
to have the PR workflow and still use gerrit for reviews
* How to deal with version branches?
   -> possibly use the Releases footer scheme of Flow
* How to keep major features/changes and their respective documentation 
in sync?
   -> we already have that problem today with bigger changes that affect 
multiple packages
   -> best practice(?): bigger changes should point to a PR with the 
respective documentation change


Martin brought up the idea to enable commenting on docs.typo3.org.
While we agreed that this could increase collaboration and be of help we 
don't think that this can make up for an improved contribution workflow.
Apart from that it also raises some issues:
* Privacy concerns (when using a 3rd party library like disqus - 
click-activation might not comply with their t&c)
* It might require moderation
* And more (see http://forum.typo3.org/index.php?t=msg&goto=688106)


So far for the workflow improvements. We also talked about the current 
documentation with regards to content based on some questions Thomas 
brought up 
(https://docs.google.com/document/d/14K-p6gvM2ufacit3SLTk2M-hqeLq6lKZm0jYL67vQus/edit?usp=sharing).

The raw protocol (by Jacob):


base distribution currently includes the demo site package
demo distribution shows off more advanced features.
base is starting point and demo site at same time.

learning by example is not a favorite way to work...
don’t need demo package to install it.

Two camps:
* I want an empty system, then I can find my way.
* it would be cool to have a cool demo site that shows off all the features.

two install paths in documentation...

Install docs need more description: Why are we doing these things? Why 
should I follow these steps?

1. know where docs are lacking (incomplete/misleading: includes need 
more detail on why to do the steps)

2. Need two different views: one with a quick overview of all the steps 
and the description of each step. Maybe there’s a way to create an 
automatic “overview” of commands so that it doesn’t have to be kept up 
to date in the two different parts of the same doc.

3. scattering of information:
There are 5 sets of documentation for Neos?
One kind of documentation with different focus points? Or per audience 
documentation like we’re striving for?
Need an obvious place to look for solutions.

We need to explain our intentions better...
w/ description it looks like more work than it is.


cookbook entries belong to the place that describes examples, not a 
single cookbook guide.

So the “cookbook” view should be a generalized view of stuff in lots of 
other docs.

A cookbook is a different thing because it combines different parts of 
the documentation.

Karsten: Cool way to do it would be:
A special cookbook block in the docs that get automatically reused in 
the cookbook section.

-- 
Bastian Waidelich