README: Link to Quick Start install page, position BPMN.iO as recommended modeller

Thanks @ressa for getting this started. So far, I always avoided providing installation instructions on project pages, as there are so many different possibilities, that what we describe only always fits for some users, but not for others. Downloading code and enabling modules is a general task that's the same for ALL modules. Individual modules should not re-describe what's been said elsewhere.

Wouldn't it be possible to refer to the general documentation on how to download and enable modules and in addition enhance the section such that people know which modules they should download and enable?

I just want to avoid that we're constantly having to update installation instructions just because there are new practices around like e.g. soon project browser.

In addition to that, the relationship to modellers could now be re-positioned as I spoke to @mxh, the maintainer of the classic modeller, last night. He agreed that we can and should make it as obvious as possible, that bpmn_io is the way to go. The other alternatives (camunda and eca_cm) will stay around, but we don't need to mention them as prominent as we currently do. And we could even discourage people from using them, pretty much like the updated project page of the classic modeller.

With that in mind, shall I propose some changes to your MR or do you want to give it another go to take it even further?

It sounds great that BPMN can be singled out as the default modeller, thanks! I created an issue for this, and added it in 📌 Idea for project page to help with on-boarding Active .

I do understand your concern, due to there being many, many options for the individual solution ... But my thinking is this:

It's crucial to get new users on-boarded easily, since it's currently way too hard and takes a lot of effort -- so let's get new users up and running in minutes, and don't force them to read the manual.

BUT, let's also add directly before (or after) a caveat that this is exactly this: A two step command, to get new users started, and then add links to the very voluminous documentation.

I would have no problem taking the responsibility of updating the download and install commands. In my opinion, it would be a small task to remember to do this (maybe it will rarely be necessary?), but the gains will be huge, due to the big influx of new users.

Wouldn't it be possible to refer to the general documentation on how to download and enable modules and in addition enhance the section such that people know which modules they should download and enable?

Actually, if BPMN is singled out as the default modeller, perhaps it could be included in ECA by default by adding it as a requirement, so that just running composer require drupal/eca will get you both ECA module and the BPMN modeller. I.e. this:

composer require drupal/eca drupal/bpmn_io

... will become this, if BPMN is a requirement:
composer require drupal/eca

Add BPMN in composer.json:

"require": {
    "php": ">=8.1",
    "ext-dom": "*",
    "ext-json": "*",
    "dragonmantank/cron-expression": "^3.1",
    "drupal/core": "^10.3||^11",
    "mtownsend/xml-to-array": "^2.0"
    "drupal/bpmn_io": "^2.0" <<<<<<<<<<<< ADD this?

Or if you prefer, we could create a new quickstart section in the ecaguide.org, which would be the two steps I added in this MR, and link to it from the README instead? https://git.drupalcode.org/project/eca/-/blob/d9f523ca4ce74d75e2526ea003...

I don't see this happening. We can't make bpmn_io a dependency of ECA as there will always be users who don't want to use the bpmn_io modeller. And it would be hard to explain, why it still always gets installed for them as well.

The dependency is the other way round: ECA is a dependency for bpmn_io and it is declared there already since day 1.

So, the easy getting started is composer require drupal/bpmn_io and that will install all you need.

What I was saying in my previous comment is that we can rephrase the text on the project page which comes from the README.md in the repository, such that BPMN.io is recognized as "THE MODELLER". Other modellers can be mentioned as options, but we can make clear what people should use by default.

The topic about installation instructions doesn't resonate well on the project page still. Even more so that project browser comes closer. Those instructions will be displayed in project browser to all those new users, but there they will be misleading, or even being wrong. For users with project browser, the installation will just be clicking a button. Such users don't want to know anything about composer require ..., all that happens in the background for them.

In summary, we can re-phrase the sections on the project page where modellers are mentioned. There we can make sure that BPMN.io is recognized as the recommended modeller, i.e. the default modeller if you will. But I don't see download and installation instructions there. As I mentioned before, there are more than 3 different ways of doing it, and describing only 1 of those 3 is wrong in my view.

In other words: the project page is the selling page for the module(s). Documentation belongs to the manuals. We won't mix that.

That's fine. I asked if it could be added in the ecaguide.org instead, what do you think about that?

Or if you prefer, we could create a new quickstart section in the ecaguide.org, which would be the two steps I added in this MR, and link to it from the README instead? https://git.drupalcode.org/project/eca/-/blob/d9f523ca4ce74d75e2526ea003...

I asked if it could be added in the ecaguide.org instead, what do you think about that?

That would be my preferred route. Adding a section Quick start to the readme, which links to the detailed explanation in the ECA Guide.

I've also reopened that thread in the MR as this isn't resolved yet in my view.

Sounds great! Perhaps we can turn the current installation page into a Quick Start guide? I have inserted the README MR text into the https://ecaguide.org/eca/install/ page and adding it as an image, for an example of how it might look. If you prefer a new section, that's also fine. But I would think, with the added text explaining that the user can change modeller, I don't see a need for two install guides.

And thanks for clarifying the situation about the README title, I have updated the MR.

I have also updated and the install section, based it on the original text, but slimmed it down. For example, the only way to install modules now is with Composer, so there's no need to mention that.

Quick Start example on install page.

And by the way, thanks for explaining how it all ties together in your comment #6. I was in a bit of a hurry when I made my short comment in #7 ... But I very much appreciate you thorough descriptions, and taking the time to explain it in detail, why the the display in Project Browser should probably not have install instructions, what the structure is in ECA, and the thinking behind it, and so on.

Re-reading your comment, I picked up on this:

In summary, we can re-phrase the sections on the project page where modellers are mentioned. There we can make sure that BPMN.io is recognized as the recommended modeller, i.e. the default modeller if you will.

This sounds great, and I made a tentative update to the README, what do you think?

I picked up another nugget, from one of your previous comment:

In addition to that, the relationship to modellers could now be re-positioned as I spoke to @mxh, the maintainer of the classic modeller, last night. He agreed that we can and should make it as obvious as possible, that bpmn_io is the way to go. The other alternatives (camunda and eca_cm) will stay around, but we don't need to mention them as prominent as we currently do. And we could even discourage people from using them, pretty much like the updated project page of the classic modeller.

So I made it even clearer that BPMN is the recommended modeller.

I also dropped a "9+" from "Drupal 9+", since we should just say "Drupal" from now on, see 🌱 [Discussion] Recommendation for dropping version numbers for external marketing of Drupal Active .

This is outstanding, thank you so much @ressa for all your effort on this. I've left a couple of minor comments in your MR. We're very close of getting this over the finish line.

The details of the https://ecaguide.org/eca/install can then be addressed in the separate repository for the ECA Guide. If you send me your email address, I can create a user account for you so that we can collaborate on that over there.

Thanks for the feedback @jurgenhaas, they were all great suggestions, and I updated the MR, and tightened up the BPMN part as well. What do you think?

Actually, since BPMN is the recommended modeller now, it could be singled out even more in the Quick Start instructions.

You can only install modules with Composer from now on, so no need to explain it.

Trimming the Quick Start guide text even more.

Let's list all modules that need to be installed, for full transparency.

This is now great, and I've merged it into 2.1.x and back ported to 2.0.x

All the outstanding tasks should be addressed in the repo of the ECA Guide at https://gitlab.lakedrops.com/drupal/documentation/eca, see #13, therefore I suggest that we mark this one as fixed.

Yes, let's mark it fixed and address the remaining task on gitlab.lakedrops.com. Thanks for a fast review and commit.

Perfect, thanks. The Kanban board for the ECA Guide can be found at https://gitlab.lakedrops.com/drupal/documentation/eca/-/boards/321

Note: I've just updated the project page with the new content from the readme file.

Automatically closed - issue fixed for 2 weeks with no activity.