In search of README for modules

[Burke Mamlin]

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

[Friedman, Roger (CDC/CGH/DGHA) (CTR)]

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?

---

Click here to unsubscribe from OpenMRS Developers' mailing list

[Saptarshi Purkayastha]

I like the idea of README.md

Also it will be useful to have those for modules...

---
Regards,
Saptarshi PURKAYASTHA

My Tech Blog:  http://sunnytalkstech.blogspot.com
You Live by CHOICE, Not by CHANCE

[Burke Mamlin]

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/
• openmrs-contrib/reports/
• openmrs-contrib/sdmx-hd-parser/README.txt

There are some examples on the web, Wordpress has a README template for plugins, etc.  As in the wikipedia article, 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

[Darius Jazayeri]

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)

[Michael Downey]

There has been an pretty good README file (if I say so myself) in the
Standalone distribution since we started putting it out. Perhaps we
could look at that for ideas?

Michael

[Burke Mamlin]

Exactly.  On github, the very first step after creating a repo is to commit the README file.[1]

While a README isn’t a required part of a GitHub repo, it is a good idea to have one. READMEs are a great place to describe your project or add some documentation such as how to install or use your project.

The github/markup project is what github uses for handling README files.  I'd propose we start by supporting README & README.txt as plain text files and, possibly, README.md and README.markdown as markdown syntax.  My only near-term hope would be to start migrating toward the common practice of including a README file with a brief description.

I've proposed a README convention on the Module Conventions page and created TRUNK-3376 as a task to get a sample README.txt file into the basicmodule archetype.

Cheers,

-Burke

[1] http://help.github.com/create-a-repo/

[Darius Jazayeri]

Someone at a real keyboard should create a ticket in emma (archetype) to automatically create a readme.txt with the could've description.

-Darius (by phone)

_________________________________________

To unsubscribe from OpenMRS Developers' mailing list, send an e-mail to LIST...@LISTSERV.IUPUI.EDU with "SIGNOFF openmrs-devel-l" in the  body (not the subject) of your e-mail.

[mailto:LIST...@LISTSERV.IUPUI.EDU?body=SIGNOFF%20openmrs-devel-l]

[Darius Jazayeri]

Module's description. Silly phone.

-Darius (by phone)

[Michael Downey]

Hi,

On Fri, May 18, 2012 at 3:51 PM, Darius Jazayeri <djaz...@gmail.com> wrote:
> Module's description. Silly phone.
>

> On May 18, 2012 12:51 PM, "Darius Jazayeri" <djaz...@gmail.com> wrote:
>>
>> Someone at a real keyboard should create a ticket in emma (archetype) to
>> automatically create a readme.txt with the could've description.

https://tickets.openmrs.org/browse/EMMA-28

Michael

[Burke Mamlin]

Done.  EMM-27

---

Click here to unsubscribe from OpenMRS Developers' mailing list