[policy] Change approach on end user ui

OK, so the real question is: What should a complete Drupal newbie expect to happen when they enable an examples module.

If it was me (and it was, at one point), I'd expect some content about the API in question. If the only thing that happened when I enabled the module was that the little check box was now checked on the extensions page, I would wonder what I had done wrong, and/or why I was wasting my time with Drupal.

And one other big thing:

If the code that is in Examples is so vital that it is a design consideration that we *need* to have copy/paste code, then Drupal isn't finished. Code which all users will be adding to their project from Examples more rightly belongs in the API, not an example. So start making your patches to ContentEntityBase or whatever, instead of Examples.

Code in Examples should always err on the side of clarity, rather than efficiency. It's documentation that happens to be executable.

• Make the help module a dependency of all the Example modules, to make sure it gets enabled.
• Put prominently in the README and on the project page that Example modules have help and that you should read it to find out what they do and how to use them.

These two are totally reasonable. We need to revisit the README anyway.

• Provide a message when the module is installed via hook_modules_installed()(is there a better way?) saying "Visit the Help page for this module for information on how to use it, and read the extensive comments in the code for information on how it was done"(actually creating a link on "this module help page").

Right, so the problem is that an extra routing system is too much for a new person to bear, whereas an implementation of hook_install() isn't. :-) Unless you want to have a hook_modules_installed() implemented in the top-level examples module, and have the message be a generic one. Which means now we have less documentation than before.

Personally, my approach to "using" a module that Examples provides is to first examine the code. If I'm not clear on what the code is doing, only then will I bother to actually enable the module. I suppose others might work the other way around, but isn't it reasonable to expect that devs will at some point be looking at the code itself? So it's not unreasonable to just have all documentation we want folks to see just in the code, and only there. Even with the hook_help() implementations, I think we should consider them examples to developers on how to implement the same - "here's how you can use hook_help() to provide info about what your module does; it's not a bad idea to do so" - rather than a serious method to provide information about the module's "functionality."

As there are devs that use the modules as starting points for their own, I don't think adding a dependency on help module is a good idea, since it's likely that many if not most will not remove that dependency for their derived modules. It's not custom practice for any module to depend on the help module, so we're potentially misleading new devs in that regard. I don't think Examples' modules should do "weird" things like that.

I'm with Garrett in #4. If I have downloaded Examples, it's because I want to see the code for how to do a block, or AJAX, or whatever the example is. Having code in there that does unrelated stuff, instead of a clean example, is a problem, because it gets in the way of it being a clean example.

So... let's just provide the documentation on how to install, use, etc. in a README.txt in each module, which is the normal place any module developer would put such information. And make sure the code is clean and well documented.

Why even make a module then? Let's just have a wiki with code snippets and be done with it.

I'm not sure why this is a big deal. We already have the hook_help text which can be factored into a page, and many modules need to define a page in order to demonstrate what they're doing. Therefore, it makes complete sense to have consistency across all modules and add a simple explanatory page for each module. All of this stuff already exists in the D7 version, ready to be ported forward.

If there is confusion about which bits of code belong to which part of the module (the help part vs. the example part), then it's a failure of documentation, and that's a problem that can be fixed.

More documentation is better than less, and being obvious is better than saying, "Well why didn't you read the README, dummy?"

So... Let's continue doing what we've been doing and make the DX better for users at all levels of experience and expertise.

We already have the hook_help text which can be factored into a page, and many modules need to define a page in order to demonstrate what they're doing.

Many need to, but many (like the filters example) do not. To do so just adds noise to the module. And, frankly, it slows down the pace of porting to D8.

OK, Can I step back and summarize? Here are, I think, the options:
[Note: Edited to talk about porting ease]

A. Continue as things were in 7:
- Each module presents a page with path examples/* that gives you a short explanation of what the module does and how to see it work.
- I'm not seeing that they provide hook_help() or README.txt files (looking at block_example for instance).

Advantages:
- When you enable the module, there is a page telling you what it does, which shows up (I think?) in the Navigation menu.

Disadvantages:
- There is code in the module that is not pertinent to the example, making it a bit more difficult to figure out what all you would really need to do to achieve the goal in your own module. In D8, this encompasses a routing.yml file, a hook_menu() or whatever it ends up being to make the Nav menu link, and a Controller class.
- Established patterns of Drupal development, such as using hook_help() and README files, are not followed, so in that way also the modules are not acting as good examples.
- Porting to D8 is a pain - involving routing.yml files and controllers.

B. Move the help to hook_help():
- Each module has a Help page that gives you a short explanation of what the module does and how to see it work.
- The overall README would need to be amended to say to go to Help (and enable the Help module).

Advantages:
- This is a more standard way to provide help in Drupal, so it demonstrates that pattern.
- There is (especially in D8) a lot less code in the module that is irrelevant to the example (just one hook).
- Porting to D8 is easier - involving moving a page function into hook_help().

Disadvantages:
- Still no README file for each module.
- It's not as obvious as having a link show up in Navigation.

C. Move the help to individual README files
- Each module would have a README file that gives you a short explanation of what the module does and how to see it work.
- The overall README would need to be amended to say to read the individual README files for details.

Advantages:
- This is an even more standard way to provide help on installation and module usage, so it demonstrates this pattern.
- No irrelevant code.
- Easier to write the help in plain text in a README than in HTML in hook_help() or in a page controller.
- Porting to D8 is easy, involving moving help text from a page function to plain text.

Disadvantages:
- It's not as obvious as having a link show up in Navigation or a topic in Help.

Is this an accurate summary? Have I missed any advantages or disadvantages of each method?

To me, (c) is the clear choice. How do others feel?

Established patterns of Drupal development, such as using hook_help() and README files, are not followed, so in that way also the modules are not acting as good examples.

Actually, current examples *are* supposed to have hook_help(). It's just that it's not consistent across D7 modules, because time in a single life is finite. :-)

Also historically we've had the argument about whether to include a README per module, because it would just duplicate the info in the top-level README. I think it's fine to move that per-module if there's something specific to talk about.

So basically A is B and C combined.

As far as #7: I think that we can be OK with anyone porting anything, as long as some reasonable docblock documentation makes it into the D8 version, and it all works. Once we decide on this stuff, I'll set up a [meta] checklist of stuff that's needed, and we can churn through some tasks like 'add hook_help() to modules without them.'

There has been a push to put examples in Core. If you actually want to get them in Core, I think there needs to be more consistency and a policy.

If this is staying as its own project for 8, then the maintainers of the project can allow whatever they want. (And although technically I am a maintainer of this project, or at least at some point I had commit access, I am certainly not an active one and do not wish to impose my views on anyone who is actually doing the work of maintaining.)

Here's the issue about moving to core: #1532612: Move Examples Project into Drupal core

Basically the decision was (as I read it), to migrate examples over after a review process, on an example-by-example basis, so it wasn't just one big lump of work.

So the process seems to be: Make an example in the examples project space, make it lovely enough for core, add it to core, repeat with next example.

I'm glad to have your input jhodgdon. If you have a different idea about D8 core migration, then we can talk about that, maybe in the other issue.

But relevant to over here: If the idea is to migrate to core, then is there a problem with adding doc page paths within core?

To me, (c) is the clear choice. How do others feel?

When put this way, I agree. Heck, maybe we can add a new example which solely shows off how to implement hook_help(). :P

Just a heads-up that I made an examples module checklist here: #2209627: [meta] Module Checklist for Examples