[D8] Include Tour module in core

[cellear]

This feature proposes that we include as a demo site a sort of "getting started" book. The exact size and scope can be worked out, but I'm picturing 20-30 pages (could be more or less) that both describes and serves as an example of a simple Drupal Backdrop "application" that a new user could dig their teeth into. Something showing at least one content type, adding at least one field, with a vocabulary, some pictures, a view or two, maybe a form. If we want to be serious about making old-style Drupal accessible, it should also include a simple custom module and a simple custom theme, or at least mention that they exist.

A big advantage of including this bit of UX documentation with the code is that it would then be versioned with the code. 5 years from later, a developer who finds themselves suddenly in charge of a 5-year-old Backdrop 1.3 system could grab an archived distribution and know what worked at the time, instead of trying to sort through anachronistic search engine results.

(feature request/documentation)

[cellear]

Context: Backdrop aims to be accessible to first time developers. When new people download it for the first time, they're going to want to look around and see what knobs they can turn and buttons they can press. Drupal doesn't include any default content -- just a disappointing suggestion that you should create some front page content. Of course, as a first timer you're not really sure what "content" even is in this context, or how you should approach it. If you do follow the link and add some content, and then choose to create an article, you'll find what you wrote is now being displayed in reverse chronological order on the home page. Drupal's default application is a very stripped down blog. (If you create a "Page" it just disappears!)

[xiongxin]

+1

[quicksketch]

Drupal doesn't include any default content -- just a disappointing suggestion that you should create some front page content.

We don't have a request for this yet, but if there's one feature we'd like Backdrop to support in 1.0 that D8 doesn't have it would be a layout tool. Though that's wishful thinking at this point with so much else to handle at the moment.

I'm not sure about this request overall. I do think it'd be great to make Backdrop more approachable, but I'm also concerned about cruft that users would need to turn off in order to actually build a site. If we ship with default example code enabled by default, there's a very good chance that example code will stay intact for a long time until the user becomes more experienced.

So overall I think the premise of the idea is good, but we'll probably have to work out a lot of details on what this example content is and how it's demonstrated as being an example. D8 added the "Tour" module for walking users through the site on a first-time install, which would work well with the suggestions here (going through content types, views, etc.) Without some unifying documentation, it would be difficult to know what's just examples and what's central to the functionality of the site. That doesn't necessarily have to be tour module though, maybe the example module could contain and document all the examples together, not unlike the contrib "Examples" module today.

p.s. I made both of you (@cellear and @xiongxin) members of the "Docs and Organization" team so you can label issues in Github. We're doing this manually until https://github.com/backdrop/backdropcms.org-issues/issues/3 is in place to automate this process.

[cellear]

My vision for this is a single "Introduction" module that you could enable during installation. Experienced developers would know not to enable it, and if it was it could be simply disabled without consequence. I believe it should default to off -- 99% of the time, Backdrop will be installed by somebody who already knows what content types, vocabularies, etc they want. The main idea of the example is to let new users know that there is a (fairly powerful) content management system that is included in Backdrop. A simple brochure-ware site, with a handful of nodes about the basics of Backdrop, suitable for somebody who had never heard of it. It wouldn't try to explain things in depth, it only needs enough to explain the concepts, with references to online resources for further information. The key goal is for it to be accurate and up-to-date with the release it's bundled with -- outdated information should be flagged as a bug and fixed. But unlike online documentation, it wouldn't get stuck in the future, either. It's married to the release of the code that it's living with. I envision something like this:

1 Introduction.

• Welcome to your installation of Backdrop. Backdrop is a framework for building websites that includes a built-in content management system. It is based on Drupal. (a few sentences about Drupal, with links)
• The briefest of histories - why and when was Backdrop created? Who and what is it intended for? 3-5 sentences.
• An explanation of what you are looking at: This is a very small example site running on your installation of Backdrop. It consists of [14 so far] pages of content. You can edit this content to get a feel for some of the things that are easy to do in Backdrop. You can delete it any time you like without major consquences (and we'll explain how to do that.) Here is a list of everything that is included in this example.
  • This intro
  • Basic architecture
  • Nodes and fields
  • Revisions - how to edit a node, and how to track and undo those edits.
  • Taxonomies
  • Views, and how to see and edit the view you're looking at (a table of contents block)
  • Adding more code: Modules, themes. (and...Apps or Features?)
  • Themes. What is a theme? The custom theme in the example - what and where it is.
  • (maybe) The custom module in the example - what and where it is.
  • A complete list of included modules and what they do.
  • (possibly, but not necessarily, other pages. Events?)
  • Vocabulary page (module, theme, etc)
  • Communities, both Backdrop and Drupal
  • Further info -- links to docs and code for both Backdrop and Drupal

2 Basic architecture.

• Includes a diagram, so that people can see how you can do pictures!
• Backdrop is built on PHP, which many web programmers are familiar with. It is extremely modular. When a page request comes in, the system assembles a collection of PHP subsystems called Modules. It then calls these modules and, when that processing is finished, creates a page which is then presented to the visitor. There are three kinds of modules:
  • Core modules that come with the system. Some of these provide such critical functionality that they should never be turned off. Others can be turned on or off depending on whether the site builder needs their functionality.
  • Contrib modules are packages of functionality that have been written by members of the Backdrop community.
  • Custom modules are modules that you have written yourself in PHP. If you know PHP and wish to use that knowledge to add functionality, it is strongly recommended that you do so by creating one or more custom modules. (Link to the custom module node)
• Once the modules have finished their work, the contents of the page are left sitting in a large PHP data structure. This structure is fed into the "Theming system" where it is turned into (typically) HTML that is presented to the site visitor. Most sites uses a single theme. (Somewhere in here we should mention layout managers like Display Suite and Panels, since they handle a lot of theming tasks at the module level.)

3 And so on.

[chrisfromredfin]

I'm wondering if this could be done on a demo site similar to how the CiviCRM project has a site that gets torn down periodically and is a "clean install" that's sort of always ready?

Of course, we lose the nature of it being a version controlled module that lives with some particular version. For that we'd need a simplytest.me equivalent, likely... then we could do it as an install profile?

[jenlampton]

I'm personally a HUGE fan of tour module and would love to see something like this in backdrop.

[quicksketch]

Tour module hasn't seen a lot of traction in Drupal 8. The meta issue for expanding Tours beyond Views has completed 0 of 15 potential tours on drupal.org after almost 2 years. I think that goes to show how difficult writing a good tour can be. I'd like to wait until Drupal 8 comes out and see the overall reaction to tours and how well they can be implemented before attempting this in Backdrop.

[jenlampton]

I'm going to close this issue, let's see if a tour module develops in contrib first, and if so we can revisit this issue for backdrop 2.x.

[jenlampton]

@docwilmot points out that this now exists: https://github.com/backdrop-contrib/joyride

Let's see if we can get a set of useful tours made for Backdrop, and if so we can re-open this issue for 2.x :)

[klonos]

Can we please reconsider this for 1.x? Drupal 9.2 ships with a solution based on https://shepherdjs.dev

Since this is something that all contrib could use, I think that it is a good fit for core.

[jenlampton]

Can we instead open this as an issue in the contrib queue? If/when we get a suitable module candidate there, we can open an "include X in core" issue with the pros/cons of doing so.

Since Tour module has proven unsuccessful in Drupal core, I don't think starting with this premise is worth pursuing anymore.

Or did you have any new information to add that might change our previous decision?

On Sun, Jun 20, 2021, 11:34 PM Greg Netsas @.***> wrote:

Reopened #89 https://github.com/backdrop/backdrop-issues/issues/89.

— You are receiving this because you modified the open/close state. Reply to this email directly, view it on GitHub https://github.com/backdrop/backdrop-issues/issues/89#event-4914802811, or unsubscribe https://github.com/notifications/unsubscribe-auth/AADBER7MMTQJ32PBRYBJ7HLTT3MQNANCNFSM4AIFA7EQ .

[klonos]

This is what the Discourse app does re either newly-introduced features, or as an intro tour:

There's a pulsating/bouncing thingy in a specific section of the UI, to draw your attention to it:

...and when you click on it, you get something like this: