I like the idea a lot. github pushes you to do this. We could look at the formats they support for guidance.
-Darius (by phone) On May 18, 2012 10:02 AM, "Burke Mamlin" <[email protected]> wrote: > 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 >> **** >> > > ------------------------------ > 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]
