search

collective / cookiecutter-plone-starter

Cookiecutter Plone Starter is a framework for jumpstarting Plone 6 projects quickly.
MIT License
18 stars 10 forks source link

cookiecutter-plone-starter is not understandable for normal people #110

Open jonaspiterek opened 6 months ago

jonaspiterek commented 6 months ago

The Problem

cookiecutter-plone-starter is not understandable for newcomers who want to create a Plone project for whatever reason. If a normal person who has basic programming knowledge would want to try Plone, set's up the cookiecutter-plone-starter and has 19 questions in front of him I highly doubt that he would be happy to answer all of those to start with a Plone project. Instead it would be the other way around. Questions popping in his head: what is a project slug? what should be my project url? which container registry should I use? And if he doesn't know what a container registry is, that would be the point where he just quits.

Solutions

Just cut the questions down to max. 10 questions, and that is still a LOT. Better would be even less. Things like the Plone, Volto, volto-generator and if volto-alpha versions should be used are just NOT necessary. Just create a project with the latest stable versions. And even if an other version of any of those is required for whatever reason you still have the option to change it in the code later on right?

Conclusion

The Plone community want's to grow. Make it easy for people to try Plone, not just with a website but with an easy understandable coding setup. Everything else come's with time, like changing versions, wanting to have a container registry or stuff like that.

sneridagh commented 6 months ago

@jonaspiterek we need more frank feedback like yours. Thanks for taking the time for doing it. It is highly appreciated.

I'm +1 for a "sensible defaults" mode and an "advanced mode".

stevepiercy commented 6 months ago

Why not use --no-input?

pipx run cookiecutter --no-input gh:collective/cookiecutter-plone-starter

If someone does not like the defaults, or hates interactive mode, then they can edit the file cookiecutter.json to their liking. We could add a line to documentation to help readers become aware of this option.

There's also the --replay option, if you've already run it once.

I don't think we can remove any of the 19 parameters.

stevepiercy commented 6 months ago

We could flip the installation documentation: https://6.docs.plone.org/install/install-from-packages.html#install-plone-6

  1. Change the default from:

    pipx run cookiecutter gh:collective/cookiecutter-plone-starter

    to

    pipx run cookiecutter --no-input gh:collective/cookiecutter-plone-starter

  2. Adjust the console output accordingly.

  3. Add a tip, something like "If you want to run through the interactive method, or use a configuration file, see Cookiecutter docs".

davisagli commented 6 months ago

Why not use --no-input? If someone does not like the defaults, or hates interactive mode, then they can edit the file cookiecutter.json to their liking. We could add a line to documentation to help readers become aware of this option.

I think this puts too much responsibility on a new user to recognize that the questions they are being asked are not particularly important, and/or to understand the existence and format of cookiecutter.json. It forces them to do more learning up front rather than providing a smooth on ramp.

I don't think we can remove any of the 19 parameters.

I know what the parameters mean and I still find it a bit annoying to have to hit enter for so many questions, when I usually just want to change 1 or 2 key values like the project name.

The way I'd like it to work is:

  1. Always prompt for a few things like project name (unless running with --no-input, of course)
  2. Then ask "Would you like to configure advanced options? [y/N]" -- If yes, ask the rest of the questions. If no, use the defaults.

Not sure if cookiecutter supports that but I imagine we could figure it out.

stevepiercy commented 6 months ago

Yo, you could put a cookiecutter inside a cookiecutter.

animus888 commented 4 months ago

I think this puts too much responsibility on a new user to recognize that the questions they are being asked are not particularly important, and/or to understand the existence and format of cookiecutter.json. It forces them to do more learning up front rather than providing a smooth on ramp.

I still think using "--no-input" is a good idea for newcomers. Maybe it's sufficient to explain in the documentation that the parameters are important and "--no-input" should only be used for starting&trying Plone/Volto very fast.

I know what the parameters mean and I still find it a bit annoying to have to hit enter for so many questions, when I usually just want to change 1 or 2 key values like the project name.

The way I'd like it to work is:

  1. Always prompt for a few things like project name (unless running with --no-input, of course)
  2. Then ask "Would you like to configure advanced options? [y/N]" -- If yes, ask the rest of the questions. If no, use the defaults.

skipping some parameters is also a good idea. I'm gonna try that with using a config file for cookiecutter-plone-starter. --> https://cookiecutter.readthedocs.io/en/stable/advanced/user_config.html#user-config If it works, this link could also be added to the documentation.