Ticket #2155 (new RFC)

Opened 11 years ago

Last modified 10 years ago

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

Change History

  Changed 11 years ago by dukeleto

+1 to more docs, -1 to plain text.

+1 to POD so that they will look pretty on Github.

  Changed 11 years ago by soh_cah_toa

Well, the reason I suggested plain text was because that's what our main README is; just so that things would be consistent. I think POD format is just as fine so long as all README's are in POD format. Would anybody be averse to changing the main README to POD format?

  Changed 11 years ago by coke

On Sun, Jul 17, 2011 at 10:23 PM, Parrot
<parrot-tickets@lists.parrot.org> wrote:
> #2155: Additional README Files in Top-Level Directories
> -------------------------+--------------------------------------------------
>  Reporter:  soh_cah_toa  |       Owner:  soh_cah_toa
>     Type:  RFC          |      Status:  new
>  Priority:  minor        |   Milestone:
> Component:  docs         |     Version:  master
>  Severity:  low          |    Keywords:  docs, readme
>     Lang:               |       Patch:
>  Platform:               |
> -------------------------+--------------------------------------------------
>
> Comment(by soh_cah_toa):
>
>  Well, the reason I suggested plain text was because that's what our main
>  README is; just so that things would be consistent. I think POD format is
>  just as fine so long as ''all'' README's are in POD format. Would anybody
>  be averse to changing the main README to POD format?

I would. I think we need at least one plain text doc for people new to
the project (and pod, and everything else) to start with.

> --
> Ticket URL: <https://trac.parrot.org/parrot/ticket/2155#comment:2>
> Parrot <https://trac.parrot.org/parrot/>
> Parrot Development
> _______________________________________________
> parrot-tickets mailing list
> parrot-tickets@lists.parrot.org
> http://lists.parrot.org/mailman/listinfo/parrot-tickets
>



-- 
Will "Coke" Coleda

  Changed 11 years ago by 1parrota@…

READMEs should always be plain text, so that standard *nix tools can
be used. Having to find special readers to make sense of files which
gain nothing from fancy formatting is a real waste of time. (That's a
general complaint, not just Parrot-related.)

  Changed 11 years ago by soh_cah_toa

I could care less what the format actually ends up being. I really just want things to be consistent (a department we are lacking in).

I've started the  soh-cah-toa/tt-2155 branch for this. Right now, the files are in POD format because I started working on it after dukeleto 's comment. If plain text is what ends up being agreed upon, reformatting it would be trivial.

in reply to: ↑ description   Changed 10 years ago by jkeenan

Replying to soh_cah_toa:

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

Directory: [name]
Summary: [short summary]

Description
...

+1 to plain-text; -1 to POD for greater consistency with Unix standards. But what you've described above is, IMO, overkill. We can make do with something like this:

README for t/

This directory and its subdirectories hold tests for Parrot and all its components.

One sentence should suffice for most of the top-level subdirs. You might need two for a subdir like frontend/ which is not as standard.

kid51

Note: See TracTickets for help on using tickets.