[Police] Add README.md to each submodule or not

I agree with your proposed resolution @jungle, moving the documentation out from each and into a README.md makes a lot of sense.

So, as an example, would it mean deleting this part from the js_example.module?

/**
 * @defgroup js_example Example: JavaScript
 * @ingroup examples
 * @{
 * Examples using Drupal 8's built-in JavaScript.
 *
 * We have two examples here.
 *
 * One 'weights' content and then sorts it by weight. This demonstrates
 * attaching JavaScript through Drupal's render arrays.
 *
 * The other demonstrates adding an accordion effect to content, through
 * Drupal's theme layer.
 */

New README.md file (D8 reference removed):

# Examples using Drupal's built-in JavaScript.

We have two examples here.

One 'weights' content and then sorts it by weight. This demonstrates
attaching JavaScript through Drupal's render arrays.

The other demonstrates adding an accordion effect to content, through
Drupal's theme layer.

Added child issue creation as a task under "Proposed resolution".

I copied and pasted the content of file_example.module file into chatgpt, and asked it to do it for me, it works well to me.

See the commit here

The sample instruction i used, FYI

Extract a REAME.md file from the content following, wrap it in less than 80 chars for each line of the answer and give me the answer in a markdown code block.

THE CONTENT OF THE MODULE FILE

So, as an example, would it mean deleting this part from the js_example.module:

Go ahead please with the suggestion in #5 if you like, thanks!

Meanwhile, we are using GitLab more and more, it parses README.md automatically. Let's do it.

Re #3 yes, for the example of removal, see this commit

Meanwhile, I am considering using ChatGPT to help and translate the READ.md file into other languages. It can lower the barrier more or less for learning from the examples module.

The file structure would be

README.md // English by default
README
   - zh-hans/README.md // Chinese,
   - es/README.md // Spanish
   - fr/README.md // French
   ... 

All README.md files will be parsed/rendered automatically on GitLab as well. And each transition should be reviewed by a native before gets committed.

Or replace the folder name README with README_translations in the suggested file structure.

Great idea with the different languages @jungle!

I found this page: https://gitlab.com/postgres-ai/database-lab/-/blob/master/translations/R...

So maybe a structure like this would work, same as theirs?

README.md // English by default
translations
  - README.chinese-zh-hans.md
  - README.spanish.md
  - README.french.md
   ... 

Maybe we should start out with creating the sub-theme README.md's from the .module content, since that text has been curated and written by one or more persons, but use ChatGPT for translating, like you suggest? At some point, the texts can be rewritten with the help of ChatGPT, if we decide so.

Also, are you able to create a "Documentation" option under "Component" for issues?

I have created 📌 Create README.md for Example: JavaScript sub-module (js_example) Needs review ready for review. Should we add translation issues for "JavaScript examples" as child issues under that issue to keep it ordered?

Also, are you able to create a "Documentation" option under "Component" for issues?

Added

README.md // English by default
translations
- README.chinese-zh-hans.md
- README.spanish.md
- README.french.md
...

The structure works, but I still think the following is better.

README.md // English by default
README-translations // A directory indicates that there are README translations inside and ONLY!
    zh-hans // Using language code is fine, I think.
        README.md // Chinese translation, Entering this zh-hans, this is the only file, and Gitlab recognizes it automatically
    es // Spanish
        README.md // Spanish translation
    ...

@ressa, I did send this issue to #examples-module and #documentaion in Drupal slack, hopefully, We can get agreement or feedback from them, and I would suggest holding on for a day or two, at least, before taking any further contributions. As I am not the only maintainer of this project, others may have different opinions. This is a kind of broken change. -- content of this module on api.drupal.org gets affected.

Many thanks!

Thanks for the new "Documentation" Component :)

I prefer to keep paths and names short, and have all files in the same folder for less clicking, which is why I suggest this structure:

examples/translations/README.german.md

This is also fine:

examples/README-translations/README.german.md

What would be the benefits of having the translations in individual folders?

Good idea, let's get some more opinions :)

- README.md
- README-translations/zh-hans/README.md
- README-translations/es/README.md
- README-translations/fr/README.md
- ...

Suggested file pathes are the above. Or another variation: replace README-translations with README.translations

- README.md
- README.translations/zh-hans/README.md
- README.translations/es/README.md
- README.translations/fr/README.md
- ...

The root is each submodule in my suggestion.

- js_example/README.md
- js_example/README.translations/zh-hans/README.md
- js_example/README.translations/es/README.md
- js_example/README.translations/fr/README.md
- ...

> What would be the benefits of having the translations in individual folders?

Let's see what others say :)

Ah yes, the README.md would get rendered, true. In that case the number of clicks required to read the content would be the same with these two paths:

- js_example/README.translations/fr/README.md
- js_example/translations/README.french.md

jungle → credited valthebald → .

> valthebald: for README.md, will this be compatible with core's help_topics module?
> valthebald: it would be great to do so
> valthebald @jungle ^
> jungle: Hi, @valthebald no plan from me for that, to me, personally, it’s optional, README.md is enough for me as a dev. it’s an Experimental module in Drupal 9, I do not think it’s widely adopted by contrib modules, — just guess.
>jungle: even implementing hook_help is optional to me.

Chatting messages from slack.

Great to see there's discussion going on, thanks for sharing!

jungle → credited andypost → .

There are more discussions continued with the above on slack, for the full messages in the thread, please view it here,

The summary we agreed on:

• Continue with extracting a README.md from the .module file to avoid credits gaming, do it in one go, or do it with 3-5 submodules per batch.
• To have an example of help_topics: help_topics_example, ✨ Add help_topics example Active , postpone the implementation or integration of help_topics into examples.
• Allow to accept translations of README.md, but optional, for the syncing. If the translation is outdated, give it a time window, e.g. one or two weeks to update or it gets removed.

Thanks @valthebald and @andypost

Updating Proposed resolution

Since the plan described here is to remove the documentation comments and replace them with an external file, I would say this is a won't fix. Documentation in code is preferable because it requires editing a single file, instead of two or more files, which makes the process easier and less prone to mistakes.

I am not sure moving the information in Markdown files has any pro using api.drupal.org does not have. api.drupal.org is able to provide a list of classes, methods, functions, and constant that Markdown files are not able to provide.