Mailing-List: contact dev-help@cordova.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cordova.apache.org
Received-SPF: pass (athena.apache.org: domain of agrieve@google.com designates
 209.85.160.48 as permitted sender)
MIME-Version: 1.0
Sender: agrieve@google.com
In-Reply-To: 
 <CADVgkyOSsFJdgw1L+Cbah-2nQhsVYnApRh5694O1sFTFXP9TCA@mail.gmail.com>
References: 
 <OFA6F0E859.DFCD843A-ON87257C89.00588959-85257C89.00592E6B@us.ibm.com>
 <CABiQX1XCSoZ8XtU=-n4Yyzdk7we=C1nk6EzYFDba=aHEmEFe=g@mail.gmail.com>
 <598EA717-5FCD-431E-8BA2-FB37A5ACFB46@gmail.com>
 <CABiQX1VxShBCXFqR5yL4TT2GB6h9xmkN_FwA6fcRriMuYH4gFw@mail.gmail.com>
 <OF916D0B06.2F1A6FA5-ON87257C89.006A457B-85257C89.006A5892@us.ibm.com>
 <CABiQX1Uu1ovv9HTGuq0qWDaE5H6-ituF8eLs+nYQXvsO9zfaWw@mail.gmail.com>
 <CADVgkyOSsFJdgw1L+Cbah-2nQhsVYnApRh5694O1sFTFXP9TCA@mail.gmail.com>
From: Andrew Grieve <agrieve@chromium.org>
Date: Mon, 24 Feb 2014 14:53:51 -0500
Message-ID: 
 <CABiQX1WtjRR9SFKwSNnuyc_3d46K4YziFM0VNdFvhoXW7eXpbQ@mail.gmail.com>
Subject: Re: [Input request] Rethinking Plugin docs
To: dev <dev@cordova.apache.org>
Cc: Lisa Seacat DeLuca <ldeluca@us.ibm.com>,
 Michael Brooks <michael@michaelbrooks.ca>
Content-Type: multipart/alternative; boundary=001a1134b978dcb2f104f32c552b

--001a1134b978dcb2f104f32c552b
Content-Type: text/plain; charset=UTF-8

+Michael

Might be helpful to write out expanded README.md files for our plugins.
Right now, they just contain a title and a link to the docs:
https://github.com/apache/cordova-plugin-file

"What it is" is covered by the first paragraph of the docs already I think.
"How to contribute" is pretty obvious for most github-hosted projects, but
I don't think that would hurt as part of the documentation either.


On Mon, Feb 24, 2014 at 2:37 PM, Brian LeRoux <b@brian.io> wrote:

> I think Mike's main consideration is that the README.md is a place for
> general project info (what it is, how to contribute, etc) whereas
> documentation, inc translations, should be in a dedicated space as standard
> convention so we can tool it. (Something like this: `doc/[lang]/index.md
> `.)
>
>
> On Mon, Feb 24, 2014 at 11:26 AM, Andrew Grieve <agrieve@google.com>
> wrote:
>
> > That was basically the question in my head as I was typing... I'd be
> happy
> > with having just a README.md, and allowing it to link to relative .md
> paths
> > if it wanted to.
> >
> >
> > On Mon, Feb 24, 2014 at 2:21 PM, Lisa Seacat DeLuca <ldeluca@us.ibm.com
> >wrote:
> >
> >> If README.md is the standard why not just call all of them README and
> not
> >> have an index.md file at all for the plugins.  What is the advantage of
> >> having both?  Seems more confusing than anything.
> >>
> >> Lisa Seacat DeLuca
> >> Mobile Engineer | t: +415.787.4589 | *ldeluca@apache.org*<
> ldeluca@apache.org>| |
> >> *ldeluca@us.ibm.com* <ldeluca@us.ibm.com> | *lisaseacat.com*<
> http://www.lisaseacat.com/>| [image:
> >> follow @LisaSeacat on twitter] <http://www.twitter.com/LisaSeacat>|
> [image:
> >> follow Lisa Seacat DeLuca on linkedin]<
> http://www.linkedin.com/in/lisaseacat>
> >>
> >>
> >>
> >>
> >>
> >> From:        Andrew Grieve <agrieve@chromium.org>
> >> To:        dev <dev@cordova.apache.org>
> >> Date:        02/24/2014 01:41 PM
> >> Subject:        Re: [Input request] Rethinking Plugin docs
> >> Sent by:        agrieve@google.com
> >> ------------------------------
> >>
> >>
> >>
> >> On Mon, Feb 24, 2014 at 12:51 PM, Marcel Kinard <cmarcelk@gmail.com>
> >> wrote:
> >>
> >> >
> >> > On Feb 24, 2014, at 12:32 PM, Andrew Grieve <agrieve@chromium.org>
> >> wrote:
> >> >
> >> > > - We may also want to include README.md files in the translations.
> >> > > doc/fr/index.md
> >> > > doc/fr/README.md
> >> >
> >> > What content do you forsee being in README.md other than a
> >> > table-of-contents to the languages? Or in other words, would it be
> >> > public-facing content that could be collapsed in to the rest of the
> >> plugin
> >> > docs?
> >> >
> >>
> >> On npmjs.org and on github, README.md's are the files that are shown
> most
> >> prominently. So, I speculate that many plugins will not provide a doc/
> >> index.md, and instead provide only a README.md.
> >>
> >>
> >> >
> >> > > - We don't need the version in the directory since we can use git
> >> tags to
> >> > > find old versions
> >> >
> >> > That makes sense.
> >> >
> >> >
> >>
> >>
> >
>

--001a1134b978dcb2f104f32c552b--