petdance/scratch — Issue #1344: Additional README Files in Top-Level Directories
Author: petdance
Created: 2011-11-01 05:39:59+00:00
State: open
Labels: docs, Pri-minor, rfc, Sev-low

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]
...
}}}

Originally http://trac.parrot.org/parrot/ticket/2155