Add Markdown to list of module documentation file types

Agreed, seems like a simple oversight. The “easier viewing on Windows” reasoning is also a bit strange if we then require Unix-style file endings (which the normal Windows editor will just ignore).

Suggested new text:

All documentation files should either have the file name extension ".txt", or be valid Markdown syntax and use the ".md" extension. Also, the file names for such files should be all-caps (for example, "README.txt" instead of "readme.txt") while the extension itself is all-lowercase (that is, "txt" instead of "TXT").

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

Marking a parent issue on Markdown policy adoption that facilitate direction or movement on this issue.

+1 for mentioning use of Markdown syntax for README files so people stop pushing back on efforts to update project documentation because it is not inline with our coding standards.

Bumping the priority because the coding standards are 18 months behind the direction core set (#3192842: Make our README more welcoming by converting it into an "entrypoint" into the Drupal ecosystem).

How about:

All 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 names for such files should be all-caps (for example, "README.txt" instead of "readme.txt") while the extension itself is all-lowercase (e.g. "txt" instead of "TXT").

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

That was accidental.

All 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 names for such files should be all-caps (for example, "README.txt" instead of "readme.txt") while the extension itself is all-lowercase (e.g. "txt" instead of "TXT").

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

Let's RTBC it to get some attention to this as the lack of guidance on this is causing needless pushback.

The Drupal coding standards has a section about the Markdown coding standards. That should be linked, instead of the Wikipedia article.

Agreed with #14; further improvements can be handled later once there's something to link to.

from the point of view of either question ("What is Markdown?" and "Are there special considerations I should be aware of when using Markdown for documenting Drupal modules?").

I think from this, https://www.drupal.org/node/2562925 could be expanded with that information and linked to the Wikipedia entry (or another URL of expertise, is there a Markdown spec documentation?). Is that an appropriate thing to begin populating documentation on that Coding Standards page now?

Is that an appropriate thing to begin populating documentation on that Coding Standards page now?

Without an issue that is marked as fixed from users who can mark it as fixed, the coding standards pages cannot be changed.

I have updated the issue summary with the improvements from comments #8 and #10 and a slight reduction of unnecessary words for clearer reading.

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"?

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 #3463660: [policy, no patch] Document high-level API concepts in an easier format

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.
Mentored by @anilu

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

Thanks for the direction for next steps.

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 ...

Took another look at this today. @jonathan1055, is correct that completing that issue summary would help. However, and in hindsight, I don't think we need to go through the Coding Standards process because this is simply bring this documentation up to date with current practice. The full process is needed for changes to the standards not making corrections in the documentation.

I have created an MR for this and changing to NR.

Thanks, looks good to me!

Thanks!

I have deleted the change record since it is not needed. And updated credit to include those from Drupalcon Atlanta who worked on the change record.

I tried to find this new page in the documentation site, I browsed looking for 'documentation' but could see nothing. Eventually I resorted to looking at the commit above, to see that it is in docs/php/coding.md so then I went back to the Doc site, opened the PHP section and still hade to scroll and search until I found it.

The paragraph is called 'File Names" but it only talks about documentaion pages, so its not really related to PHP at all. Maybe there should be a new top-level "Documentation" menu item for this kind of standard? The MR was only opened after most of the discussion above, and I'm sorry I did not get back to this issue and raise this question quickly. It's not a big problem. Do we have a general issue open for restructuring the menu, etc, or maybe there are other migration tasks still to be done first?

@jonathan1055, can you open a new issue for #49? Thanks.