volto: Too many installation docs (and other suggested improvements)

We have too many Volto installation docs.

I would strongly advocate for one, and only one, way to install Volto for development in Plone 6.

This would make it easier to maintain installation documentation and reduce frustration of developers.

As a couple of side notes:

  1. I would require, not make it optional, to use nvm. Alternatively, we should make a statement such as, “The Volto development team uses nvm for installing and managing versions of Node.js. We do not support any other node version manager or the lack of one. If you do not use nvm, then we assume you know what you are doing and can resolve issues on your own.”
  2. Provide clear paths to install Volto using either Docker or a manual installation. The current docs are not structured clearly because all headings are at the same level and not in order. The proposed version aims to provide that structure and order.
  3. State “For simplicity in documentation, we use bash for a shell. Adjust commands according to your preferred shell flavor.”
  4. Specify what characters are valid in a project name for npm init yo @plone/volto. Letters, number, dashes, underscores, other characters?
  5. Use “Install”, not “Getting Started”, buried under “Introduction”. Elevate it.
  6. Separate “Installation” from “Development” documentation. Volto (and any other core Plone package) should still have its specific documentation for development purposes, such as for running tests.

About this issue

  • Original URL
  • State: closed
  • Created 2 years ago
  • Reactions: 2
  • Comments: 18 (7 by maintainers)

Most upvoted comments

There is a difference between the whole organization (which has, and will always have, private repos for things like the admin&infra team and security team) and “projects”, which can have per-project settings. As long as a project (which is just a collection of issues) has issues from public repos, the project visibility can be set to “public” as well. This does not change who can interact with it.

I’ve set the visibility of the “Install docs” and “Release Plone 6 docs” projects to “public”

I’m going to close this issue, because we have resolved most of the issues and consolidated documentation into include files. Specific issues remain, but they can be addressed separately.

I’ve created a project to track all Install-related issues, Install Docs.