Improve/Update: Installation Docs

[svx]

Current

Our installation part is partly out of date [ie. windows #734 ], missing parts [ie. docker #524 ], divided into different places [ie minimal buildout install under requirements http://docs.plone.org/manage/installing/requirements.html#minimal-build] and UI docs are not always in sync with https://github.com/plone/Installers-UnifiedInstaller/tree/master/docs.

One other point, is that we should shorten the currently long parts of these docs into more shorter onces, it is hard to read and follow.

Future

IMHO we should pay more attention for different audiences and/or even split it into trying and installing.

This can be challenging for us and we should coordinate that with the plone.org team to make sure that we use the same terms, descriptions and wording on plone.org and the docs.

Example

One solution could be:

Trying Plone:

• Online Demo
• VirtualBox Kit (include docs via papyrus)
• Default Docker (include docs via papyrus0

Install Plone:

• UI Installer [default] (via papyrus)

Install Plone [advanced aka production deployment]

• Own buildout
• UI Installer (via papyrus)
• Ansible Kit (via papyrus)
• Docker, persistent mode, own image, .... (via papyrus)
• Snappy (via papyrus)
• A install with a distributed ZEO setup like add a section on distributed server environment #700

Third Party Distributions

IMHO not on docs.plone.org but we should mention them on plone.org ?

Next Steps

• Update/Improve https://github.com/plone/simple-plone-buildout/tree/5.0.6

  • rename [IMHO the usage of simple should go away]
  • update README with links and make it conform to our style guide
  • create /docs with nice and understandable docs, possible with screen shots

• Check https://github.com/plone/Installers-UnifiedInstaller/tree/master/docs

  • remove 'old' install docs and 'embed' ^^^, easier to maintain in one place

• Finish Docker docs and include them

• Sort out audiences and sort content according to them

[svx]

Looking further into installing:

Under: http://docs.plone.org/manage/installing/requirements.html we have different instructions than under https://github.com/plone/simple-plone-buildout, this could lead to confusion, IMHO we should settle on one example buildout, preferable based on the UI one ?

If you are a more experienced user you will use your own anyway.

Ideas ? Comments ? Anyone ?

[stevepiercy]

I think three audiences is plenty: demo, install, and develop.

I get lost in the docs for how to install Plone because I don't know which method is best for me. There's too many choices–UI, buildout, Docker, Vagrant, and so on–and it's not clear which is appropriate for my intended purpose. I think for each audience, there should be one and only one installation method, support it well, and let the community offer alternatives. (FWIW, I followed the instructions from the PloneConf training https://training.plone.org/5/plone_training_config/instructions.html#installing-plone-without-vagrant which suffers from the same too many choices problem, but that may be OK in a training.)

I would also suggest the removal of the section Minimal build from Plone Installation Requirements because this is requirements, not how to install, and is redundant to Installation.

[svx]

@stevepiercy IMHO there is a difference between install for developing/local and a proper deployment for production.
That is what I meant with install and install (advanced) .

[stevepiercy]

@svx explicit would be clear and give more context for a given audience, e.g., "Install Plone for development environments" and "Install Plone for production environments". What do you think?

"Demo Plone" would be a more clear heading for trying Plone, too.

I would like to see one example buildout for each of development and production environments.

[svx]

The docs of https://github.com/plone/simple-plone-buildout got an update.

Short term proposal:

• remove old 'minimal buildout docs' from within requirements [weird location anyway]
• include the improved docs of https://github.com/plone/simple-plone-buildout under installation

[tkimnguyen]

It's on my plate to update https://plone.org/download to steer people to different setup/install methods depending on their needs.

[tkimnguyen]

plone/ploneorg.core#208

[tkimnguyen]

Made some changes to https://plone.org/download and yeah I agree that https://docs.plone.org/manage/installing/requirements.html needs urgent help. FFS it mentions using the Windows installer which we haven't had for years...

[stevepiercy]

Superseded by Install Docs