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 Mon, 24 Feb 2014 19:53:51 GMT
+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