Roger, I was only referring to the fact that we've at least got something called readme.txt in trunk. The fact that it's lowercase and only contains a description of the file structure is, how should I say, "room for improvement." I did not mean in any way to suggest that the OpenMRS trunk/readme.txt would set our conventions. I probably shouldn't have mentioned it.
Some better examples in our repository: - openmrs-contrib/csv-concept-importer/trunk/<http://svn.openmrs.org/openmrs-contrib/csv-concept-importer/trunk/> - openmrs-contrib/reports/<http://svn.openmrs.org/openmrs-contrib/reports/> - openmrs-contrib/sdmx-hd-parser/README.txt<http://svn.openmrs.org/openmrs-contrib/sdmx-hd-parser/README.txt> There are some examples<https://www.cs.washington.edu/education/courses/326/02wi/homework/hw5/good-readmes.html> on the web, Wordpress has a README template<http://wordpress.org/extend/plugins/about/readme.txt> for plugins, etc. As in the wikipedia article<http://en.wikipedia.org/wiki/README>, it would be nice for a README to include a brief description (background/purpose for people who know nothing about the code), configuration/installation instructions, operation instructions, contact info, and (possibly) known bugs. At this point, I'd just be happy if we just had a description. A module ID is not enough to sufficiently describe most modules (or maybe I'm the only one who doesn't instantly recognize the meaning of DDU, CHIRDL, CHICA, AMRS, RKS, DHIS, DSS, I2B2, JSS, NBS, NCD, EMPI, PIXPDQ, RGRTA, and YANK among many others). :-) I'm proposing that we promote using a README.txt file (git projects can use README.md) with a simple template like: == Description == This is the long description of this module/contribution. No limit on size and you can use Markdown. Replace this text with any background or description of your work that will help someone who knows nothing about your project understand what it is and its purpose. When appropriate, direct people to where they can find more information. == Installation == Describe how to install this work – e.g., for a module: requirements/configuration steps to compile, where to find the omod, and direction to use the OpenMRS module admin page to install the omod. Most modules could use a standard template. Contribs or special modules might have different instructions. -Burke On Fri, May 18, 2012 at 11:18 AM, Friedman, Roger (CDC/CGH/DGHA) (CTR) < [email protected]> wrote: > Burke --**** > > The OpenMRS README file only describes the project layout, it is not > useful for understanding the purpose of OpenMRS. What level of detail > would you expect in the file, given that the most detailed information > would be on the wiki?**** > > ** ** > > *From:* [email protected] [mailto:[email protected]] *On Behalf Of *Burke > Mamlin > *Sent:* Friday, May 18, 2012 10:59 AM > *To:* [email protected] > *Subject:* [OPENMRS-DEV] In search of README for modules**** > > ** ** > > Devs,**** > > ** ** > > Could we migrate toward a convention of using a README file at the root of > each module? I know there's a place for a description in the config.xml, > but it's not very friendly when trying to scan through > modules<http://svn.openmrs.org/openmrs-modules/>and understand their purpose. > And I'm sure an improved module repository > will help some day, but not all modules make it into the module repository. > **** > > ** ** > > For example, adopt a convention of placing a README (e.g., one of README, > README.txt, README.md) containing a description of the module in the root > of each module's tree (or in trunk/ if the module uses the trunk/, > branches/, tags/ folder convention). This is already a prevailing > convention in open source coding, right?**** > > ** ** > > OpenMRS has a "readme.txt" file in trunk. We could use the same for > contribs.**** > > ** ** > > Thoughts?**** > > ** ** > > -Burke**** > ------------------------------ > > Click here to > unsubscribe<[email protected]?body=SIGNOFF%20openmrs-devel-l>from > OpenMRS Developers' mailing list > **** > _________________________________________ To unsubscribe from OpenMRS Developers' mailing list, send an e-mail to [email protected] with "SIGNOFF openmrs-devel-l" in the body (not the subject) of your e-mail. [mailto:[email protected]?body=SIGNOFF%20openmrs-devel-l]
