id,summary,reporter,owner,description,type,status,priority,milestone,component,version,severity,resolution,keywords,cc,lang,patch,platform
2155,Additional README Files in Top-Level Directories,soh_cah_toa,soh_cah_toa,"In a recent [http://lists.parrot.org/pipermail/parrot-dev/2011-July/006010.html email] to parrot-dev, kid51 brought up the question of whether each top-level directory could benefit from a small README file describing their purpose.

A few of them already do but I think making this a consistent practice is a great idea. The purpose of these directories is not always self-evident and personally, I still don't know what they all are for. I don't see any immediate disadvantages to this other than a small increase in size. Even so, if the cost of further clarifying our directory structure is just a couple extra kilobytes, I say ""so what.""

The format of each README should be consistent and in plain text. Perhaps something like:

{{{
Directory: [name]
Summary: [short summary]

Description
-----------

[more verbose description]

Subdirectories
--------------

[name - short summary]
[name - short summary]
...
}}}
",RFC,new,minor,,docs,master,low,,"docs, readme",,,,