Posted by gisle on July 9, 2014 at 9:57am
So far in my reviews, I have not objected to applicants having a README.md instead of README.txt.. This mainly because it does the job just as well, and it also looks like README.md may one day be supported by drupal.org infrastructure (see: Allow README.md to optionally render a project page).
However, the Module documentation guidelines says
All modules should provide a README.txt file.
There is no mention of README.md at all.
I would like to change this into. "All modules should provide a README.txt or README.md file."
Any objections?
Comments
+1 from me.
+1 from me.
knaddison blog | Morris Animal Foundation
Ditto.
Ditto.
+1 from me, too. Seems like
+1 from me, too. Seems like you already did the edit to the doc page. I guess we don't need a Drupal core documentation issue?
Drupal core documentation issue not required
I don't think so.
Before I started changing it, it even said that README.txt was optional (but recommended) for contributed modues, and also that there was no consensus regarding content and format.
However, I think that these days, we should nudge new maintainers towards better and more standardized documentation. So I've toned down the "optional" part and also expanded the description of the format to provide what I hope is better guidance to new maintainers regarding content and format (i addition to saying that
README.mdis fine).For Drupal 8, I think that
README.mdshould be considered the preferred documentation for a project, and that it should be used to automatically generate the project page ondrupal.org/projects(unless overridden), and also displayed (filtered by by the markdown filter) as the default help text if there is nohook_help()in the project.It's 2014
It's 2014. I think that README.md should be the preferred documentation format for all modules going forward.
One, markdown is almost a defacto standard now in the development community as a whole. We can use it in various places on the drupal.org sites already.
Two, we need to encourage better documentation across the board. The README is often the only source of documentation for a project, especially in the beginning. Markdown in the README will help with this.
Three, as @gisle mentions, it could be a nice feature to automagically display these for projects for in-site help. Some modules will display the README.txt via hook_help already, and a handful will do markdown processing on it of the module is installed. Requiring this for Drupal 8 would be great, but it is probably too late for this (it is a great idea, though, and I may work on a patch to do it).
FWIW, I think I have a better recipe for displaying a README in hook_help(). It's in the mobile_detect module if anyone wants to take a look. I can't remember where I got the inspiration from for this.
A good patch would still be nice
It may be too late for requiring it, but if a good patch exists, it should have a good chance of being committed soon after Drupal 8 is officially released.
Yeah I've started to move to
Yeah I've started to move to README.md a lot, and am happy with this move.
The hook_help() trick seen in mobile_detect seems like a jazzed-up version of the practice I started doing many years ago and then included when I wrote the original module documentation guidelines (and also started the search for a README.txt formatting convention back then too)
I think suggested we even do something like that (directly surfacing all modules READMEs) directly from the admin/modules page when that was getting improved but then I started looking at using advanced_help and putting my bigger docs into HTML anyway... long ago.
Anyway, yes to README.md . Github has made me appreciate it a lot.
Really helpful
+1 by keeping the Readme.md with Readme.txt
I have reviewed my last 2 projects and found that the Readme.md is very useful while keeping the hooks & other details.
Naveen Valecha
https://www.valechatech.net