Conflict between coding standards and module documentation guidelines on file naming

I have updated the issue summary with the improvements from comments #8 and #10.

The next thing to do will be to use the new Coding Standards issue template being trialed on #3387167: Add an issue template for the Coding Standards project → . This contains the new process for getting standards agreed and documentation pages updated.

@jonathan1055, thanks for updating the IS.

I haven't found 'all-caps' in a dictionary so am suggesting a change. Also, I don't think the extension includes the '.' nor do I think the examples need to be given twice. So, how about this

Documentation files should either be in plain text with the file name extension "txt", or be valid Markdown syntax with the file name extension "md".

The base file name should be all upper case and the extension itself should be all-lowercase.

Examples: README.md, README.txt, INSTALL.md, TODO.txt, CHANGELOG.txt.

I have to agree with #13 and disagree with #14, sorry. I do not see a point to linking to Wikipedia and then, later, re-linking to D.O - this feels like following a process for the sake of the process. Majority of developers already know what Markdown is. If we want it to be formatted in a specific way according to Drupal standards, then we have a page for it in D.O. Although that page does not have much right now, it will be filled separately outside of this issue, which is not about the Markdown format but about the file naming conventions.

I'm putting this issue back to Needs work to discuss this more.

Updated to use the new coding standards issue template.

Are there changes to be made to "The Module documentation guidelines"?

#23 None of which I'm aware. What did you have in mind? This issue assumes that the implication in the module documentation guidelines (that the use of markdown for such documentation is appropriate) is correct.

I had no idea when I pointed out the discrepancy five years ago that it would turn out to be so controversial. 😉

Yes, let's remove the link to Wikipedia. It could link to something else, but what; GitLab's flavor, CommonMark or something else? So, let's just remove the link all together..

As an avid documentation person, I support the idea that such a sophisticated software ecosystem as Drupal must embrace and promote a more modern markup format for writing all our valuable documentation.

I can imagine even some automated tools to implement for converting current .txt files into .md files. And of course, the CommonMark initiative is the best option to promote for our community, I believe.

@baluertl, you may interested in 🌱 Document high-level API concepts in an easier format Active

The README template links to these Markdown resources:

For a quick introduction to Markdown, see Markdown Guide's Basic Syntax or GitLab Flavored Markdown (GLFM) for a more comprehensive run-down. Please also review the Drupal Coding Standards for Markdown files → prior to making changes.

https://www.drupal.org/docs/develop/managing-a-drupalorg-theme-module-or... →

I agree that Markdown should be used for documentation files, it's a wonderful format!

PS. Thanks for the link @quietone, I am adding as related, to connect these issues.

With three supporters, I guess next step is writing a Change Record?

The Process for Changing Coding Standards

1. Create an issue in the Coding Standards project queue using the provided Coding Standards issue template.
2. At least two additional active community members (contrib module maintainers, active patch contributors, etc) need to agree to support the change in the form of a comment on the issue.
3. The issue should have a change record. <<<< We are here
   
   [...]

From https://www.drupal.org/project/coding_standards →

@ressa, yes, the change record is next.

Hi my name is Ana (@anilu) and we are at Drupalcon Atlanta mentored contribution workshop and are working in documentation for Media core module

Hi -- my name is Derrek (@derrekc) and we are at DrupalCon ATL.

Documentation to complete this ticket can be found in the ticket tags > about tags https://www.drupal.org/list-changes/drupal →

Here is the "Change Record" link:
https://www.drupal.org/node/3515822 →

Description:
Please modify the Drupal coding standards to bring them in line with the rest of the Drupal ecosystem, and reflect the encouragement of the use of markdown documentation files for Drupal projects.

That is not the description for a change record. A change record describes the change done; it does not ask to modify something.

See the existing Coding Standards change record, such as The "short ternary" operator "?:" must be used where the first operand of a ternary expression matches the condition → , or Use UpperCamelCase for enum and enum case values → , which are not created as Drupal core change records.

Thanks @avpaderno, we are still working on this issue. We are at the mentoring room at Drupalcon Atlantla working on this. The change record is still in draft version but we have completed the requested change to the documentation in https://www.drupal.org/node/161085#readme →

I am working on the at DC ATL 25 with @derrekc; being mentored by @anilu

I'm working on this issue with with @derrekc at ATL 25; being mentored by @anilu

If any of the new people recently commenting and working on this issue would like to contribute here, then issue summary needs to have the "Benefts" section filled in. Currently it only has the original text from in the template:

If we adopted this change, the Drupal Project would benefit by ...