You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cordova.apache.org by Lisa Seacat DeLuca <ld...@us.ibm.com> on 2014/02/24 17:13:56 UTC
[Input request] Rethinking Plugin docs
I noticed for the 3.4 release that the documentation for each of the
plugins redirects to the github repository for each plugin and a document
under doc/index.md
http://cordova.apache.org/docs/en/3.4.0/cordova_plugins_pluginapis.md.html#Plugin%20APIs
If we want to have translations for each of the plugins then we're going
to need to rethink this a little. Here are two options:
1. similar to the cordova-docs dir, we could have a language directory as
the parent.
ex. doc/en/index.md
and while we're at it we probably need the version as well
ex. doc/en/3.4.0/index.md
If we do this then at least we can have the documentation for each
language. But that doesn't solve the problem of the user being always
redirected to the english version of the documentation and not their
specific language.
2. Is it hard to do a build of the index.md for each plugin similar to how
we build the cordova-doc md files into html files? If it were seamless
and part of the other documentation it would make my life
*coughTranslationcough* so much easier. Plus it won't be as confusing on
end users having to choose their language more than one time.
It'd be nice to get some input from everyone before I start writing a
complicated automated script for the plugin translations.
Lisa
Lisa Seacat DeLuca
Mobile Engineer | t: +415.787.4589 | ldeluca@apache.org | |
ldeluca@us.ibm.com | lisaseacat.com | |
Re: [Input request] Rethinking Plugin docs
Posted by Lisa Seacat DeLuca <ld...@us.ibm.com>.
Translation Update:
1. I have updated the automated scripts for crowdin to pull in the
documentation for cordova-docs and the 17 plugin repository .md files.
There are currently 72 files available for translation in our tooling. It
is available as always, here: https://crowdin.net/project/cordova. For
information on the nitty-gritty checkout the wiki page:
https://wiki.apache.org/cordova/CordovaTranslations
2. We kinda discussed the way the documentation is currently referencing
the english version of the documentation within github. We'll need to
come up with a better way of building the plugin documentation into the
current html pages. I opened a JIRA issue:
https://issues.apache.org/jira/browse/CB-6137
3. Another issue that was brought to my attention by Carlos (thanks
Carlos) is there is currently no clear way for users to know that
translations exist. So I have opened a JIRA issue:
https://issues.apache.org/jira/browse/CB-6136. It would be nice if to the
left of the drop down there was a message such as "Switch languages or
documentation version here:"
Please share with your social network a tweet to get people to help with
translations.
ex.
The @apachecordova documentation is now broken out for each plugin. We
need YOUR help translating! @crowdin https://crowdin.net/project/cordova
Thanks,
Lisa
Lisa Seacat DeLuca
Mobile Engineer | t: +415.787.4589 | ldeluca@apache.org | |
ldeluca@us.ibm.com | lisaseacat.com | |
From: Shazron <sh...@gmail.com>
To: "dev@cordova.apache.org" <de...@cordova.apache.org>
Date: 02/24/2014 12:47 PM
Subject: Re: [Input request] Rethinking Plugin docs
I agree with Andrew's points in #1. We have to update the 3.4.0 docs
nonetheless, since the URLs do not point to a specific tagged version.
On Mon, Feb 24, 2014 at 9:32 AM, Andrew Grieve <ag...@chromium.org>
wrote:
> My thoughts here:
>
> 1.
> - We may also want to include README.md files in the translations.
> - I like not having a subdir for en/ so as to differentiate it as the
one
> the others are based off of
> - We don't need the version in the directory since we can use git tags
to
> find old versions
>
> maybe:
> doc/index.md
> doc/fr/index.md
> doc/fr/README.md
> doc/es/index.md
> doc/es/README.md
>
> 2.
> The plan is to render these on plugins.cordova.io, so we can certainly
add
> logic there to maintain language pref.
>
>
>
>
> On Mon, Feb 24, 2014 at 11:13 AM, Lisa Seacat DeLuca <ldeluca@us.ibm.com
> >wrote:
>
> > I noticed for the 3.4 release that the documentation for each of the
> > plugins redirects to the github repository for each plugin and a
document
> > under doc/index.md
> >
> >
> >
>
http://cordova.apache.org/docs/en/3.4.0/cordova_plugins_pluginapis.md.html#Plugin%20APIs
> >
> > If we want to have translations for each of the plugins then we're
going
> > to need to rethink this a little. Here are two options:
> >
> > 1. similar to the cordova-docs dir, we could have a language directory
as
> > the parent.
> > ex. doc/en/index.md
> > and while we're at it we probably need the version as well
> > ex. doc/en/3.4.0/index.md
> >
> > If we do this then at least we can have the documentation for each
> > language. But that doesn't solve the problem of the user being always
> > redirected to the english version of the documentation and not their
> > specific language.
> >
> > 2. Is it hard to do a build of the index.md for each plugin similar to
> > how we build the cordova-doc md files into html files? If it were
> seamless
> > and part of the other documentation it would make my life
> > *coughTranslationcough* so much easier. Plus it won't be as confusing
on
> > end users having to choose their language more than one time.
> >
> > It'd be nice to get some input from everyone before I start writing a
> > complicated automated script for the plugin translations.
> >
> >
> > Lisa
> >
> > 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>
> >
> >
>
Re: [Input request] Rethinking Plugin docs
Posted by Shazron <sh...@gmail.com>.
I agree with Andrew's points in #1. We have to update the 3.4.0 docs
nonetheless, since the URLs do not point to a specific tagged version.
On Mon, Feb 24, 2014 at 9:32 AM, Andrew Grieve <ag...@chromium.org> wrote:
> My thoughts here:
>
> 1.
> - We may also want to include README.md files in the translations.
> - I like not having a subdir for en/ so as to differentiate it as the one
> the others are based off of
> - We don't need the version in the directory since we can use git tags to
> find old versions
>
> maybe:
> doc/index.md
> doc/fr/index.md
> doc/fr/README.md
> doc/es/index.md
> doc/es/README.md
>
> 2.
> The plan is to render these on plugins.cordova.io, so we can certainly add
> logic there to maintain language pref.
>
>
>
>
> On Mon, Feb 24, 2014 at 11:13 AM, Lisa Seacat DeLuca <ldeluca@us.ibm.com
> >wrote:
>
> > I noticed for the 3.4 release that the documentation for each of the
> > plugins redirects to the github repository for each plugin and a document
> > under doc/index.md
> >
> >
> >
> http://cordova.apache.org/docs/en/3.4.0/cordova_plugins_pluginapis.md.html#Plugin%20APIs
> >
> > If we want to have translations for each of the plugins then we're going
> > to need to rethink this a little. Here are two options:
> >
> > 1. similar to the cordova-docs dir, we could have a language directory as
> > the parent.
> > ex. doc/en/index.md
> > and while we're at it we probably need the version as well
> > ex. doc/en/3.4.0/index.md
> >
> > If we do this then at least we can have the documentation for each
> > language. But that doesn't solve the problem of the user being always
> > redirected to the english version of the documentation and not their
> > specific language.
> >
> > 2. Is it hard to do a build of the index.md for each plugin similar to
> > how we build the cordova-doc md files into html files? If it were
> seamless
> > and part of the other documentation it would make my life
> > *coughTranslationcough* so much easier. Plus it won't be as confusing on
> > end users having to choose their language more than one time.
> >
> > It'd be nice to get some input from everyone before I start writing a
> > complicated automated script for the plugin translations.
> >
> >
> > Lisa
> >
> > 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>
> >
> >
>
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.
> > > > >> >
> > > > >> >
> > > > >>
> > > > >>
> > > > >
> > > >
> > >
> >
> >
>
Re: [Input request] Rethinking Plugin docs
Posted by Andrew Grieve <ag...@chromium.org>.
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 Lisa Seacat DeLuca <ld...@us.ibm.com>.
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@us.ibm.com | lisaseacat.com | |
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
<mi...@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
<ag...@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
<cm...@gmail.com>
> > >> wrote:
> > >>
> > >> >
> > >> > On Feb 24, 2014, at 12:32 PM, Andrew Grieve
<ag...@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 Steven Gill <st...@gmail.com>.
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 <ag...@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 <cm...@gmail.com>
> > >> wrote:
> > >>
> > >> >
> > >> > On Feb 24, 2014, at 12:32 PM, Andrew Grieve <ag...@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>.
+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 <cm...@gmail.com>
> >> wrote:
> >>
> >> >
> >> > On Feb 24, 2014, at 12:32 PM, Andrew Grieve <ag...@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 Brian LeRoux <b...@brian.io>.
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 <ld...@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*<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: 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 <cm...@gmail.com>
>> wrote:
>>
>> >
>> > On Feb 24, 2014, at 12:32 PM, Andrew Grieve <ag...@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...@google.com>.
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 <ld...@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*<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: 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 <cm...@gmail.com>
> wrote:
>
> >
> > On Feb 24, 2014, at 12:32 PM, Andrew Grieve <ag...@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 Brian LeRoux <b...@brian.io>.
I think Mike Brooks has extensive thinking wrt to this. Wait for his reply!
On Mon, Feb 24, 2014 at 11:21 AM, Lisa Seacat DeLuca <ld...@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*<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: 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 <cm...@gmail.com>
> wrote:
>
> >
> > On Feb 24, 2014, at 12:32 PM, Andrew Grieve <ag...@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 Lisa Seacat DeLuca <ld...@us.ibm.com>.
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@us.ibm.com | lisaseacat.com | |
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 <cm...@gmail.com>
wrote:
>
> On Feb 24, 2014, at 12:32 PM, Andrew Grieve <ag...@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>.
On Mon, Feb 24, 2014 at 12:51 PM, Marcel Kinard <cm...@gmail.com> wrote:
>
> On Feb 24, 2014, at 12:32 PM, Andrew Grieve <ag...@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 Marcel Kinard <cm...@gmail.com>.
On Feb 24, 2014, at 12:32 PM, Andrew Grieve <ag...@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?
> - 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>.
My thoughts here:
1.
- We may also want to include README.md files in the translations.
- I like not having a subdir for en/ so as to differentiate it as the one
the others are based off of
- We don't need the version in the directory since we can use git tags to
find old versions
maybe:
doc/index.md
doc/fr/index.md
doc/fr/README.md
doc/es/index.md
doc/es/README.md
2.
The plan is to render these on plugins.cordova.io, so we can certainly add
logic there to maintain language pref.
On Mon, Feb 24, 2014 at 11:13 AM, Lisa Seacat DeLuca <ld...@us.ibm.com>wrote:
> I noticed for the 3.4 release that the documentation for each of the
> plugins redirects to the github repository for each plugin and a document
> under doc/index.md
>
>
> http://cordova.apache.org/docs/en/3.4.0/cordova_plugins_pluginapis.md.html#Plugin%20APIs
>
> If we want to have translations for each of the plugins then we're going
> to need to rethink this a little. Here are two options:
>
> 1. similar to the cordova-docs dir, we could have a language directory as
> the parent.
> ex. doc/en/index.md
> and while we're at it we probably need the version as well
> ex. doc/en/3.4.0/index.md
>
> If we do this then at least we can have the documentation for each
> language. But that doesn't solve the problem of the user being always
> redirected to the english version of the documentation and not their
> specific language.
>
> 2. Is it hard to do a build of the index.md for each plugin similar to
> how we build the cordova-doc md files into html files? If it were seamless
> and part of the other documentation it would make my life
> *coughTranslationcough* so much easier. Plus it won't be as confusing on
> end users having to choose their language more than one time.
>
> It'd be nice to get some input from everyone before I start writing a
> complicated automated script for the plugin translations.
>
>
> Lisa
>
> 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>
>
>