cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andrew Grieve <agri...@chromium.org>
Subject Re: [Input request] Rethinking Plugin docs
Date Tue, 04 Mar 2014 18:05:10 GMT
Michael - any input here on merging doc -> README.md?, or if we do this how
translations should go?

e.g. README.md, doc/fr/README.md



On Mon, Feb 24, 2014 at 3:27 PM, Lisa Seacat DeLuca <ldeluca@us.ibm.com>wrote:

> README.md merge +1
>
> I understand the idea behind keeping the documentation outside of the
> README.md but given that the "how to contribute" and other info is
> generally the same across all of the plugins and is available on the wiki,
> etc. it's probably redundant to put it in each repo as well.  That being
> said it probably wouldn't hurt to have a link on the top of the README.md's
> pointing back to the main cordova project info.
>
>
> 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:        Steven Gill <stevengill97@gmail.com>
> To:        "dev@cordova.apache.org" <dev@cordova.apache.org>
> Cc:        Lisa Seacat DeLuca/San Francisco/IBM@IBMUS, Michael Brooks <
> michael@michaelbrooks.ca>
> Date:        02/24/2014 03:08 PM
> Subject:        Re: [Input request] Rethinking Plugin docs
> ------------------------------
>
>
>
> I personally think we should merge the two into README.md. Our readme files
> in the plugins are useless right now. Might as well combine some of the
> info that should be in the readme + index.md so we have all of the
> important information shown prominently.
>
>
> On Mon, Feb 24, 2014 at 11:53 AM, Andrew Grieve <agrieve@chromium.org
> >wrote:
>
> > +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.
> > > >> >
> > > >> >
> > > >>
> > > >>
> > > >
> > >
> >
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message