Ticket #2155 (new RFC)

Opened 3 years ago

Last modified 3 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 3 years ago by dukeleto

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

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

  Changed 3 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 3 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 3 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 3 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 3 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.