You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cordova.apache.org by Andrew Grieve <ag...@chromium.org> on 2014/03/04 19:05:10 UTC
Re: [Input request] Rethinking Plugin docs
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 <ld...@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*<ld...@apache.org>| |
> *ldeluca@us.ibm.com* <ld...@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 <st...@gmail.com>
> To: "dev@cordova.apache.org" <de...@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 <ag...@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* <ld...@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 <ag...@chromium.org>
> > > >> To: dev <de...@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.
> > > >> >
> > > >> >
> > > >>
> > > >>
> > > >
> > >
> >
>
>
Re: [Input request] Rethinking Plugin docs
Posted by Michael Brooks <mi...@michaelbrooks.ca>.
I'm more supportive of Michal's thoughts, although I understand the
practicality of Andrew's approach.
Ideal world:
- plugins.cordova.io renders all markdown files in docs/**/*.md
- plugins.cordova.io allows switching the language (globally across the
site, like any normal website)
Algorithm for default npm page:
1. If exists docs/index.md
2. If exists docs/en/index.md
3. If exists README.md
README.md vs index.md
- README.md (or just README) is a top-level file for projects
- Our documentation is a mark-up language that's render to HTML files
- Our documentation should use the naming pattern of HTML files NOT
project distribution files
- README.md should not appear in our docs directory
Reality
- Anis will know best, but this approach might not be do-able in the
short-term.
- Ideally, our next doc generator could be pluggable into
plugins.cordova.io to do the heavy lifting
- The multiple pages could be displayed as separate HTML pages or
simply the GitHub gist-style for multiple files.
- A short-term solution may be:
1. If only one markdown file exists in docs/**/*.md, then render it as
the npm page
2. If multiple markdown files exist in docs/**/*.md, then render a
table of contents as the npm page (from all the files)
On Wed, Mar 5, 2014 at 12:23 PM, Michal Mocny <mm...@chromium.org> wrote:
> on plugman publish:
> if (exists docs/en/README.md) use that;
> else use README.md;
>
> ??
>
> The reason I suggest that is because I think relative links will not work
> very well if we have the EN docs at a different level than the other
> languages.
>
> -Michal
>
>
> On Wed, Mar 5, 2014 at 2:50 PM, Andrew Grieve <ag...@chromium.org>
> wrote:
>
> > 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 <mm...@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 <ag...@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* <ld...@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 <st...@gmail.com>
> > > > > > > To: "dev@cordova.apache.org" <de...@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* <ld...@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 <ag...@chromium.org>
> > > > > > > > > >> To: dev <de...@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.
> > > > > > > > > >> >
> > > > > > > > > >> >
> > > > > > > > > >>
> > > > > > > > > >>
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>
Re: [Input request] Rethinking Plugin docs
Posted by Michal Mocny <mm...@chromium.org>.
on plugman publish:
if (exists docs/en/README.md) use that;
else use README.md;
??
The reason I suggest that is because I think relative links will not work
very well if we have the EN docs at a different level than the other
languages.
-Michal
On Wed, Mar 5, 2014 at 2:50 PM, Andrew Grieve <ag...@chromium.org> wrote:
> 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 <mm...@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 <ag...@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* <ld...@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 <st...@gmail.com>
> > > > > > To: "dev@cordova.apache.org" <de...@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* <ld...@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 <ag...@chromium.org>
> > > > > > > > >> To: dev <de...@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.
> > > > > > > > >> >
> > > > > > > > >> >
> > > > > > > > >>
> > > > > > > > >>
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>
Re: [Input request] Rethinking Plugin docs
Posted by Andrew Grieve <ag...@chromium.org>.
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 <mm...@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 <ag...@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 <ag...@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* <ld...@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 <st...@gmail.com>
> > > > > To: "dev@cordova.apache.org" <de...@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* <ld...@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 <ag...@chromium.org>
> > > > > > > >> To: dev <de...@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.
> > > > > > > >> >
> > > > > > > >> >
> > > > > > > >>
> > > > > > > >>
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > > >
> > > >
> > >
> >
>
Re: [Input request] Rethinking Plugin docs
Posted by Michal Mocny <mm...@chromium.org>.
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 <ag...@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 <ag...@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* <ld...@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 <st...@gmail.com>
> > > > To: "dev@cordova.apache.org" <de...@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* <ld...@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 <ag...@chromium.org>
> > > > > > >> To: dev <de...@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.
> > > > > > >> >
> > > > > > >> >
> > > > > > >>
> > > > > > >>
> > > > > > >
> > > > > >
> > > > >
> > > >
> > > >
> > >
> >
>
Re: [Input request] Rethinking Plugin docs
Posted by Andrew Grieve <ag...@chromium.org>.
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 <mi...@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 <ag...@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* <ld...@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 <st...@gmail.com>
> > > To: "dev@cordova.apache.org" <de...@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* <ld...@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 <ag...@chromium.org>
> > > > > >> To: dev <de...@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.
> > > > > >> >
> > > > > >> >
> > > > > >>
> > > > > >>
> > > > > >
> > > > >
> > > >
> > >
> > >
> >
>
Re: [Input request] Rethinking Plugin docs
Posted by Michael Brooks <mi...@michaelbrooks.ca>.
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 <ag...@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* <ld...@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 <st...@gmail.com>
> > To: "dev@cordova.apache.org" <de...@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 <ag...@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* <ld...@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 <ag...@chromium.org>
> > > > >> To: dev <de...@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.
> > > > >> >
> > > > >> >
> > > > >>
> > > > >>
> > > > >
> > > >
> > >
> >
> >
>