Ticket #2155 (new RFC)
Additional README Files in Top-Level Directories
Reported by: | soh_cah_toa | Owned by: | soh_cah_toa |
---|---|---|---|
Priority: | minor | Milestone: | |
Component: | docs | Version: | master |
Severity: | low | Keywords: | docs, readme |
Cc: | Language: | ||
Patch status: | Platform: |
Description
In a recent 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] ...