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 Wed, 05 Mar 2014 19:50:10 GMT
That's a hairy point of this change for sure. Not sure what the best would
be. Maybe treat doc/fr/README.md as based on /README.md
I think the majority of third-party plugins will write only README.md, and
have no doc/ at all, so having it be a special case is worth it I think.


On Wed, Mar 5, 2014 at 2:44 PM, Michal Mocny <mmocny@chromium.org> wrote:

> How does that work with proposal for i18n?  Ideally the docs/ tree is
> identical in each language, so I think we want the top level docs
> (README.md or index.md) to be in the docs/en/ tree as well.
>
> Perhaps we leave the README.md empty and change plugman publish to bundle
> docs/en/index.md instead?
>
> Or perhaps we make README.md == docs/en/index.md always?
>
> -Michal
>
>
> On Wed, Mar 5, 2014 at 2:25 PM, Andrew Grieve <agrieve@chromium.org>
> wrote:
>
> > The discussion so far has been:
> > - npm, github, surface README.md prominently
> > - our README.md files are essentially empty
> > - let's delete doc/index.md and put it all in README.md
> > - plugins.cordova.io will render the README.md prominently
> >
> >
> > On Wed, Mar 5, 2014 at 1:25 PM, Michael Brooks <michael@michaelbrooks.ca
> > >wrote:
> >
> > > Andrew, do you mean merging all of the documentation into the README.md
> > or
> > > do you mean translating the README.md to other languages?
> > >
> > >
> > > On Tue, Mar 4, 2014 at 10:05 AM, Andrew Grieve <agrieve@chromium.org>
> > > wrote:
> > >
> > > > 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